Как подключить MCP-сервер к Cursor

MAATRIX

Cursor умеет писать код, но сам по себе не видит вашу базу данных, не может дернуть внешний API и не знает, что лежит в соседнем репозитории — это добавляют MCP-серверы. Проблема в том, что в интерфейсе редактора нет очевидной кнопки «подключить сервер»: нужно найти правильный раздел настроек и отредактировать JSON руками, а форматов конфига у Cursor на самом деле два — под локальный процесс и под удалённый сервер по сети. Ниже — практический разбор: где искать настройку, как выглядит конфиг, как подключить готовый сервер и что делать, если он не заработал. Что такое MCP и зачем он нужен — отдельная тема, без жаргона она разобрана в статье что такое MCP простыми словами. Здесь она не повторяется — сразу к подключению в Cursor. Если раньше уже настраивали MCP-серверы в Claude Desktop, многое покажется знакомым: оба приложения используют один и тот же протокол и почти идентичную структуру mcpServers в конфиге — детали подключения к Claude Desktop разобраны в статье как подключить MCP-сервер к Claude Desktop, но конфиги у приложений разные файлы, и один в другой скопировать напрямую не выйдет из-за разных путей и нюансов.

Что нужно подготовить до начала

Cursor свежей версии. Поддержка MCP есть у Cursor уже давно, но раздел настроек и формулировки в интерфейсе за последний год несколько раз переезжали и переименовывались, поэтому если Cursor не обновлялся месяцами — сначала обновите его через Help → Check for Updates или встроенный автообновитель.

Node.js или Python — под тип сервера. Как и с любым MCP-сервером, готовые пакеты обычно написаны либо на JS и запускаются через npx, либо на Python и запускаются через uvx. Проверьте, что нужный рантайм на месте:

node --version
npx --version
uvx --version

Если команды не находятся — ставьте Node.js с официального сайта nodejs.org или uv с astral.sh, отдельно на этом останавливаться не будем.

Решение, где именно нужен сервер — в одном проекте или везде. У Cursor конфиг MCP бывает двух уровней: привязанный к конкретному проекту (репозиторию) и общий для всех окон редактора. Это стоит решить до правки файла, иначе один и тот же сервер случайно окажется прописан дважды в разных местах.

Где находится настройка MCP-серверов в Cursor

Открывается через настройки самого Cursor: значок шестерёнки в правом верхнем углу или сочетание клавиш Cmd+Shift+J на macOS (Ctrl+Shift+J на Windows/Linux) открывает Cursor Settings, где есть раздел MCP (в разных версиях подписан как «MCP» или «MCP & Integrations» — расположение может слегка отличаться от билда к билду, но раздел всегда один и тот же по сути: список подключённых серверов и кнопка добавить новый).

Кнопка «+ Add new MCP Server» (или «New MCP Server») в этом разделе — самый быстрый путь: она создаёт файл конфига, если его ещё нет, и сразу открывает его на редактирование. Под капотом это всё тот же обычный JSON-файл, который можно найти и вручную:

Глобальный конфиг (действует во всех проектах и окнах):

~/.cursor/mcp.json

На Windows — %USERPROFILE%\.cursor\mcp.json.

Конфиг конкретного проекта (действует только внутри этого репозитория):

<путь-к-проекту>/.cursor/mcp.json

Разница важна на практике. Глобальный mcp.json — личная настройка: сервер, который нужен вам во всех проектах (например, доступ к своей заметочной базе или таск-трекеру). Проектный .cursor/mcp.json лежит внутри репозитория, его можно закоммитить в git и раздать команде — все, кто откроет проект в Cursor, увидят тот же набор серверов. Если сервер с одинаковым именем описан и там, и там, Cursor не станет их складывать — проектная версия действует поверх глобальной для этого конкретного окна, поэтому дублировать один и тот же сервер в обоих файлах не стоит, это только путает при отладке.

Формат конфига: локальный процесс и удалённый сервер

Внутри mcp.json — один ключ верхнего уровня mcpServers, а дальше произвольные имена серверов. У Cursor, в отличие от чисто локального Claude Desktop, есть два рабочих варианта записи для каждого сервера.

Локальный сервер (stdio) — Cursor сам запускает процесс рядом с собой, ровно как это делает Claude Desktop:

{
  "mcpServers": {
    "имя-сервера": {
      "command": "npx",
      "args": ["-y", "имя-пакета"],
      "env": {
        "ПЕРЕМЕННАЯ": "значение"
      }
    }
  }
}

• command — исполняемый файл: npx, uvx, python или прямой путь к бинарнику.
• args — аргументы командной строки, разбитые по элементам массива.
• env — переменные окружения для процесса (токены, ключи); Cursor, как и Claude Desktop, не подтягивает их автоматически из вашего .zshrc или .bashrc, процесс стартует в чистом окружении.

Удалённый сервер (url) — если MCP-сервер уже развёрнут где-то в сети (например, на своём VPS) и слушает HTTP или SSE, Cursor умеет подключаться к нему напрямую по адресу, без запуска локального процесса:

{
  "mcpServers": {
    "имя-сервера": {
      "url": "https://mcp.example.com/sse",
      "headers": {
        "Authorization": "Bearer ваш-токен"
      }
    }
  }
}

Поле headers нужно, если сервер требует авторизацию — большинство сетевых MCP-серверов её требуют, потому что в отличие от локального stdio-процесса адрес в сети в теории доступен кому угодно. Если своего размещённого сервера пока нет, а тема интересна — сам процесс развёртывания на VPS с Streamable HTTP или SSE и настройкой обратного прокси разобран отдельно в статье как поднять MCP-сервер на VPS.

Подключаем готовый сервер: пример на filesystem

Для первой проверки удобнее взять локальный сервер без токенов и внешних сервисов — официальный сервер файловой системы из документации MCP. Он просто даёт модели читать и писать файлы в разрешённой папке.

Проверьте, что пакет вообще стартует, прямо в терминале до правки конфига:

npx -y @modelcontextprotocol/server-filesystem /Users/имя/Documents/projects

Команда должна либо зависнуть без вывода (сервер ждёт подключения по stdio — это нормально), либо завершиться без ошибок. Остановите её Ctrl+C и впишите тот же вызов в mcp.json — глобальный, если сервер нужен во всех проектах, или проектный, если только в этом репозитории:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/имя/Documents/projects"
      ]
    }
  }
}

На Windows путь в args нужно писать с экранированными слэшами: "C:\\Users\\имя\\Documents\\projects". После сохранения файла возвращаться в терминал не обязательно — дальше проверка идёт прямо в интерфейсе Cursor.

Проверка что сервер подключился

В разделе MCP настроек Cursor каждый описанный сервер появляется отдельной строкой с индикатором статуса. Зелёная точка и число рядом с именем сервера означают, что процесс запустился и Cursor успешно получил от него список инструментов — обычно там же можно раскрыть строку и увидеть их названия. Красный индикатор или иконка ошибки — сервер не стартовал; клик по строке или значку с многоточием открывает вывод процесса (stdout/stderr), где почти всегда видна причина: не найдена команда, не хватает переменной окружения, неверный путь.

Дальше — проверка в самом чате. Инструменты MCP доступны только в режиме агента (Agent), а не в обычном текстовом чате с моделью без доступа к инструментам, поэтому убедитесь, что выбран именно агентский режим. Попросите что-то, что требует обращения к подключённому серверу — «покажи список файлов в подключённой папке». Если всё настроено верно, Cursor перед ответом покажет вызов конкретного инструмента и, если автоматическое выполнение инструментов не включено в настройках, запросит подтверждение перед его выполнением.

Типичные проблемы и как их решать

Cursor не наследует ваш PATH. Как и Claude Desktop, Cursor на macOS запускается не из терминала, поэтому если npx или uvx установлены через nvm или другой менеджер версий и не видны в системном PATH графических приложений, команда в command просто не найдётся, хотя в терминале всё работает. Решение — прописать в command абсолютный путь, полученный командой which npx (macOS/Linux) или where npx (Windows), вместо голого имени команды.

Один и тот же сервер задублирован в глобальном и проектном конфиге. Если сервер с одинаковым именем есть и в ~/.cursor/mcp.json, и в .cursor/mcp.json проекта, легко запутаться, какая версия параметров реально используется в текущем окне. Держите правило: личные серверы — только в глобальном файле, командные и специфичные для проекта — только в проектном.

Сервер в списке, но выключен. У серверов в разделе MCP настроек есть переключатель — можно временно отключить сервер, не удаляя его из конфига. Если инструменты не появляются, а статус вроде бы зелёный, первым делом проверьте, что тумблер включён.

Битый JSON ломает разом все серверы. Пропущенная запятая или незакрытая кавычка в mcp.json — и Cursor молча не поднимет ни один сервер из этого файла, включая ранее рабочие. Перед сохранением стоит прогнать файл через любой JSON-валидатор.

401 или ошибка авторизации у удалённого сервера. Для серверов с полем url почти всегда нужен корректный Authorization в headers — просроченный или неверно вставленный токен даёт ошибку уже при попытке получить список инструментов, а не при сохранении конфига.

Cursor в целом тормозит или обрывает соединения из России. Если проблема не в конкретном MCP-сервере, а в том, что сам Cursor периодически «зависает» на автодополнении или обрывает чат — это, скорее всего, не про MCP, а про маршрут до серверов ИИ. Такая ситуация и её решение через собственный сервер за границей разобраны в статье Cursor через свой сервер: настройка доступа.

Частые вопросы