Как подключить Cursor к n8n: включите instance-level MCP в настройках n8n, скопируйте Server URL, оканчивающийся на /mcp-server/http, затем установите плагин n8n в Cursor Settings > Plugins и вставьте этот URL. Cursor откроет браузер для OAuth-входа, после подтверждения инструменты n8n появятся в чате. Отдельно нужно выдать MCP-доступ конкретным воркфлоу, иначе агент видит только превью из search_workflows.
Включение instance-level MCP в n8n
Работу начинают на стороне n8n. По документации проекта, доступ включается в разделе Settings > Instance-level MCP кнопкой Enable MCP access, и для этого нужны права instance owner или admin. Если у вас нет прав owner или admin, попросите владельца или администратора включить MCP-доступ на инстансе.
После включения страница делится на три секции: Connection details со статусом MCP и кнопкой Connect, Access со счётчиком воркфлоу, открытых для MCP-клиентов, и Connected clients со списком подключённых клиентов и их правами. Владельцы и админы дополнительно видят там Allowed callback URLs.
Server URL берут из Settings > Instance-level MCP > Connect a client. Документация n8n указывает, что адрес оканчивается на /mcp-server/http. В README официального плагина для Cursor приведён пример вида https://acme.app.n8n.cloud/mcp-server/http: поддомен и домен подставляются ваши, хвост пути остаётся тем же.
Разметка настроек с секциями Connection details, Access и Connected clients, диалог Connect a client и Allowed callback URLs доступны с версии n8n 2.33.0. На более старых сборках страница показывает упрощённый вид без пошаговой настройки под конкретный клиент. В этом случае клиент настраивают вручную по инструкциям из раздела MCP client connection examples.
Отключение доступа живёт в той же секции Connection details: элемент управления статусом MCP и пункт Disable. n8n запрашивает подтверждение, потому что отключение разрывает связь со всеми подключёнными клиентами и отзывает их доступ. Включить доступ обратно можно позже.
Для self-hosted инстансов настройками MCP разрешено управлять через переменные окружения. Полное удаление функции выполняется переменной N8N_DISABLED_MODULES=mcp: она убирает MCP-эндпоинты и скрывает связанные элементы интерфейса.
Проверьте перед переходом к Cursor: доступ включён, вы вошли под владельцем или админом, Server URL скопирован целиком вместе с хвостом /mcp-server/http. Эти три условия закрывают большинство последующих сбоев.
Установка плагина n8n в Cursor
Официальный плагин n8n для Cursor описан в README репозитория n8n-io/n8n-cursor-plugin. Плагин добавляет один MCP-сервер и не хранит учётные данные: вход в n8n выполняется через OAuth.
Порядок установки по README:
- В Cursor откройте Cursor Settings > Plugins, найдите n8n и установите его.
- Cursor запросит n8n MCP server URL. Возьмите его в n8n: Settings > Instance-level MCP, кнопка Connect.
- Выберите Cursor и скопируйте Server URL вида
https://acme.app.n8n.cloud/mcp-server/http. - Вставьте URL в Cursor и нажмите Save.
- Войдите в n8n в браузере и подтвердите доступ.
Изменить адрес позже можно через Cursor Settings > Plugins > n8n > Configure. В командном маркетплейсе Cursor админ задаёт URL один раз для всех участников, при этом каждый участник входит под своей учётной записью n8n.
Требования к окружению из README: инстанс n8n в облаке или на своём сервере и включённый instance-level MCP. Если вы разворачиваете плагин локально, README описывает копирование в ~/.cursor/plugins/local и команду rsync для обновления файлов. Локальные плагины Cursor показывает с заглавной буквы в названии, например N8n, а установленные из маркетплейса используют displayName из plugin.json.
Ручная настройка через mcp.json
Плагин — не единственный путь. Документация Cursor по MCP описывает подключение серверов через файл mcp.json в двух местах: .cursor/mcp.json внутри проекта для инструментов конкретного репозитория и ~/.cursor/mcp.json в домашней папке для инструментов, доступных везде.
Для удалённого сервера, работающего по HTTP или SSE, запись содержит url и, при необходимости, заголовки. Документация Cursor приводит такой шаблон:
{
"mcpServers": {
"n8n": {
"url": "https://<ваш-инстанс>/mcp-server/http",
"headers": {
"Authorization": "Bearer ${env:N8N_MCP_TOKEN}"
}
}
}
}
Подставьте свой адрес вместо <ваш-инстанс>. Токен храните в переменной окружения N8N_MCP_TOKEN: документация Cursor советует передавать секреты через переменные и не хардкодить их. Синтаксис ${env:NAME} Cursor разрешает в полях command, args, env, url и headers. Дополнительно доступны ${userHome}, ${workspaceFolder}, ${workspaceFolderBasename} и ${pathSeparator}.
Документация Cursor перечисляет три транспорта: stdio для локальных серверов, которыми управляет сам Cursor, и SSE либо Streamable HTTP для серверов, развёрнутых как отдельная служба с URL-эндпоинтом и авторизацией через OAuth. Сервер n8n относится к удалённому типу, поэтому в записи используется url.
Для серверов с OAuth документация Cursor допускает статические клиентские учётные данные в mcp.json вместо динамической регистрации. Это применимо, когда провайдер выдаёт фиксированный CLIENT_ID, требует внести redirect URL в белый список или не поддерживает динамическую регистрацию OAuth 2.0. В объекте auth указывают CLIENT_ID, при необходимости CLIENT_SECRET и список scopes. Значения тоже поддерживают интерполяцию: "CLIENT_ID": "${env:MCP_CLIENT_ID}".
Cursor использует фиксированные redirect URL: http://localhost:8787/callback для десктопного приложения и https://www.cursor.com/agents/mcp/oauth/callback для веб-версии и облачных агентов. Если вход выполняется из обоих мест, оба адреса регистрируют в OAuth-приложении провайдера.
OAuth-вход и API key
Диалог Connect a client в n8n предлагает два метода: OAuth (рекомендуемый) и API key. В README плагина для Cursor описан именно OAuth: после вставки URL Cursor открывает браузер, вы входите в n8n и подтверждаете доступ. Плагин при этом не хранит учётные данные.
При выборе OAuth в диалоге n8n вы указываете тип клиента в списке Your client. Документация n8n группирует клиентов на CLI (Claude Code, Codex, Gemini CLI), Web (Claude.ai, ChatGPT, Mistral Vibe) и IDE (Cursor, VS Code, Windsurf) и показывает шаги под выбранный тип. Для IDE предлагается ссылка установки в один клик там, где редактор её поддерживает, либо копирование Server URL и ручная вставка конфигурации. Завершает процесс переход в n8n с подтверждением доступа.
API key нужен, когда клиент не проходит OAuth-поток или когда требуется долгоживущий токен без браузерного входа. В диалоге Connect a client переключитесь на вкладку API key: n8n автоматически создаёт персональный токен доступа, привязанный к вашей учётной записи, при первом открытии вкладки. Скопируйте либо готовый блок Configuration JSON с заполненными Server URL и заголовком Authorization: Bearer, либо отдельные значения Server URL и токена для клиентов с другим форматом конфигурации.
После закрытия вкладки n8n показывает только замаскированное значение токена, и скопировать его повторно не получится без ротации. Ротация выполняется там же: Settings > Instance-level MCP, Connection details, Connect, вкладка API key, кнопка генерации нового токена рядом с замаскированным значением. При генерации нового токена n8n отзывает предыдущий. После ротации обновите значение во всех подключённых MCP-клиентах.
Клиенты с API key не отображаются в списке Connected clients: они аутентифицируются bearer-токеном. Отзыв доступа для них выполняется через ротацию токена.
Выдача MCP-доступа воркфлоу
Включённый instance-level MCP открывает клиентам превью всех воркфлоу, к которым у текущего пользователя есть доступ, через инструмент search_workflows. Полные данные, запуск и изменение воркфлоу становятся доступны только после явного включения MCP-доступа для конкретного воркфлоу. Это ключевое ограничение: без него агент в Cursor видит список, но не может работать с содержимым.
Документация n8n приводит три способа включения:
| Способ | Где выполняется | Что нажимается |
|---|---|---|
| Через страницу Workflows enabled | Settings > Instance-level MCP > Workflows enabled | Кнопка Enable workflows, выбор воркфлоу, Enable |
| Через редактор воркфлоу | Открытый воркфлоу | Меню Workflow (…) > Settings > переключатель Available in MCP |
| Через список воркфлоу | Раздел Workflows | Меню на карточке воркфлоу > Enable MCP access |
Страница Workflows enabled доступна с версии n8n 2.2.0 и в версии 2.42.0 получила текущее название. С неё можно открыть воркфлоу или его проект, отозвать доступ через меню действий, обновить описание воркфлоу и включить доступ для дополнительных воркфлоу.
Управление доступом на уровне проектов и папок появилось в n8n 2.24.0. В списке воркфлоу проекта или папки открывается меню Options, затем Manage MCP access с пунктами Enable MCP и Disable MCP. Переключатель действует на все воркфлоу, которые сейчас лежат в выбранной папке или проекте, пропуская те, что уже находятся в нужном состоянии.
Автоматическое открытие новых воркфлоу внедряется постепенно с n8n 2.36.0, и настройка может быть видна не на каждом инстансе. Включается она в Settings > Instance-level MCP переключателем Auto-expose new workflows. По умолчанию настройка выключена и действует только на воркфлоу, созданные после включения; существующие сохраняют текущее состояние. Менять её могут только владельцы и админы инстанса.
Описания воркфлоу помогают агенту различать задачи. Их добавляют со страницы Workflows enabled через меню действий Edit description или из редактора воркфлоу через Workflow menu (…) > Edit description.
Проверка подключения
Проверка идёт по цепочке от Cursor к n8n. Сначала убедитесь, что инструменты n8n появились в Cursor: документация Cursor показывает доступные MCP-инструменты в разделе Available Tools, а серверы включаются и выключаются из Customize на боковой панели. Если инструменты не появились, README плагина советует перезапустить Cursor после установки URL.
Второй шаг — поиск воркфлоу. Попросите агента найти воркфлоу по имени: search_workflows возвращает превью. Затем попросите открыть полные данные того же воркфлоу. Если доступ к ним отклонён, вернитесь к разделу о выдаче доступа и проверьте переключатель Available in MCP.
Третий шаг — тестовый запуск. Инструмент execute_workflow по умолчанию работает в production-режиме и запускает опубликованную версию воркфлоу; ручной режим запускает текущую неопубликованную версию. Большинство остальных MCP-инструментов работают с неопубликованными воркфлоу. Выберите воркфлоу без внешних побочных эффектов и запустите его, чтобы убедиться, что права выданы корректно.
Четвёртый шаг — проверка логов. Документация Cursor описывает просмотр логов MCP: откройте панель Output (Cmd+Shift+U на macOS, Ctrl+Shift+U на Windows и Linux), выберите MCP Logs в выпадающем списке и проверьте сообщения об ошибках подключения, проблемах аутентификации и падениях сервера. Логи показывают инициализацию сервера, вызовы инструментов и текст ошибок.
Пятый шаг — ревизия прав. В Settings > Instance-level MCP > Connected clients видно до трёх ваших подключённых клиентов с их правами и общее число клиентов с доступом. Выбор клиента открывает детали, Revoke access отключает его. Ссылка View all показывает остальных, а переключение на представление всех пользователей — клиентов других сотрудников.
Разбор типовых ошибок
Ошибки при подключении сводятся к нескольким повторяющимся случаям. Ниже — таблица с причиной и действием.
| Симптом | Причина | Действие |
|---|---|---|
| Ошибка 404 при подключении | Использован неполный URL | Взять полный Server URL из n8n вместе с хвостом /mcp-server/http |
| Инструменты n8n не появляются | Cursor не перечитал конфигурацию | Перезапустить Cursor после установки URL |
| Инструменты n8n показаны дважды | Сервер добавлен и плагином, и через ~/.cursor/mcp.json |
Удалить одну из записей |
| Вход в n8n не проходит | Админ ограничил Allowed callback URLs | Добавить http://localhost:8787/callback и https://www.cursor.com/agents/mcp/oauth/callback |
| Сообщение о недостатке прав при авторизации | MCP-доступ выключен на инстансе | Попросить владельца или админа включить MCP access и повторить вход |
| Клиент не подключается за прокси | Промежуточный слой срезает заголовки MCP | Добавить MCP-Protocol-Version, Mcp-Method и Mcp-Name в белый список |
Разберём подробнее сообщение о недостатке прав. Документация n8n описывает страницу с текстом о том, что у пользователя нет достаточных прав для авторизации запроса. Для instance MCP-сервера это означает, что MCP-доступ на инстансе выключен. Пока сервер работает, любой вошедший пользователь может подтвердить клиента; пока доступ выключен, n8n отказывает всем. Решение — включить MCP access и подключить клиент заново.
Ограничение Allowed callback URLs настраивают владельцы и админы в Settings > Instance-level MCP > Access. По умолчанию n8n разрешает любой callback URL. Режим Only trusted URLs пропускает только перечисленные адреса, и тогда оба callback-адреса Cursor нужно внести в список и сохранить.
Если инстанс работает за обратным прокси, балансировщиком или веб-приложением-файрволом, проверьте, что промежуточный слой пропускает заголовки MCP-Protocol-Version, Mcp-Method и Mcp-Name. Документация n8n указывает, что CORS-политика разрешает эти заголовки с версии 2.36.0, и при фильтрации по белому списку их нужно туда добавить. Иначе клиенты могут не подключиться или откатиться на более старую версию протокола.
Официальный путь и сторонний n8n-MCP
Официальный путь строится на встроенном instance-level MCP-сервере n8n и плагине n8n для Cursor. Он даёт одну точку подключения на инстанс, централизованную аутентификацию и выбор воркфлоу, открытых для доступа. Включённые воркфлоу легко находятся и запускаются без отдельной настройки под каждый из них.
Сторонний проект czlonkowski/n8n-mcp решает другую задачу. Его README описывает сервер для документации и построения воркфлоу, работающий с Claude Desktop, Claude Code, Windsurf и Cursor. Проект поддерживает опциональный доступ к официальному instance-level MCP и использует отдельный секрет, который хранится тем же способом, что и N8N_API_KEY. Ключи этих двух систем различны, и переносить возможности стороннего сервера на официальный путь нельзя.
Выбор между ними определяется задачей. Официальный путь подходит, когда нужно, чтобы агент Cursor работал с воркфлоу вашего инстанса: искал их, запускал, создавал и редактировал. Сторонний сервер нужен, когда требуется справочный слой по нодам и построению воркфлоу, работающий независимо от вашего инстанса.
Создание и редактирование воркфлоу через instance-level MCP доступно с версии n8n 2.13.0. Документация n8n советует в роли MCP-клиентов использовать кодинг-агентов, которые специализируются на генерации и проверке TypeScript-кода. Для них существует набор n8n Skills из репозитория n8n-io/skills: 13 модулей по практикам работы с воркфлоу, более 50 справочных документов и примеров, хуки для автоматической подгрузки нужного руководства и 14-й мета-модуль using-n8n-skills-official, направляющий агента к подходящему навыку. Навыки написаны на Markdown, их можно читать, форкать и адаптировать под свои соглашения.
Частые вопросы
Почему Cursor не видит инструменты n8n после установки URL?
Чаще всего Cursor не перечитал конфигурацию. README плагина советует перезапустить Cursor после установки Server URL. Если перезапуск не помог, проверьте, что URL скопирован целиком вместе с хвостом /mcp-server/http. Также убедитесь, что MCP-доступ включён на инстансе n8n под владельцем или админом.
Чем OAuth отличается от API key при подключении?
OAuth — рекомендуемый метод: Cursor открывает браузер, вы входите в n8n и подтверждаете доступ, а плагин не хранит учётные данные. API key нужен, когда клиент не проходит OAuth-поток или требуется долгоживущий токен. Токен привязан к вашей учётной записи, а после закрытия вкладки n8n показывает только замаскированное значение.
Почему агент находит воркфлоу, но не может его запустить?
Включённый instance-level MCP открывает клиентам только превью воркфлоу через search_workflows. Полный доступ, запуск и изменение появляются после явного включения MCP-доступа для конкретного воркфлоу. Включите переключатель Available in MCP в настройках воркфлоу или через страницу Workflows enabled.
Как отозвать доступ у подключённого клиента?
Откройте Settings > Instance-level MCP > Connected clients, выберите клиента и нажмите Revoke access. n8n отключает клиента сразу, и для возврата доступа ему потребуется подключиться и войти заново. Клиенты с API key в этом списке не отображаются: их доступ отзывается ротацией токена.
Что делать при ошибке 404?
При ошибке 404 проверьте полный Server URL из n8n в разделе Settings > Instance-level MCP вместе с хвостом /mcp-server/http и вставьте его в Cursor заново. Такой способ проверки описан в разделе Troubleshooting README плагина.