Перейти к основному содержанию

Установка MCP-сервера в Cursor: пошаговый гайд для 2026

Локальное подключение Python MCP-сервера в Cursor: установка uv, настройка mcp.json, проверка инструментов и разбор ошибок запуска и доступа.

· Atomno MCP ·
  • cursor
  • tutorial
  • mcp
  • setup
Ноутбук с учебным фрагментом mcp.json: команда uvx и имя пакета; отдельно показаны tools/list и tools/call.
Учебный фрагмент настройки. После запуска отдельно проверьте список инструментов и ответ выбранного инструмента.

В этой статье — локальное подключение MCP-сервера в Cursor на примере atomno-mcp-fns-check. Оно подходит для клиента с запуском через uvx; удалённый MCP подключается иначе. Успешный запуск процесса ещё не означает, что внешний источник ответил или что доступен размещённый режим подписки.

Шаг 0: Установите uv

uv — инструмент для Python от Astral. Команда uvx — сокращение для uv tool run: она запускает инструменты в отдельном Python-окружении. Это разделение зависимостей, а не защитная песочница для недоверенного кода. Устанавливайте только изученный пакет.

Способы установки опубликованы в официальной инструкции Astral.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Альтернатива через pipx:

pipx install uv

Эти команды выполняют установку. После неё откройте новый терминал и проверьте доступность команд, не ожидая конкретного номера версии из статьи:

uv --version
uvx --version

Если команда не найдена, проверьте путь установки и PATH своей системы. Команда может быть доступна в терминале, но отсутствовать в окружении процесса Cursor.

Шаг 1: Откройте mcp.json

В документации Cursor предусмотрены два уровня:

УровеньПутьОбласть действия
Глобальный~/.cursor/mcp.jsonВаши проекты
Проектный.cursor/mcp.json в корне проектаЭтот проект

На Windows домашняя папка обычно доступна как %USERPROFILE%; глобальный файл находится в %USERPROFILE%\.cursor\mcp.json. Если файл уже содержит серверы, сохраните копию и добавьте новую запись в существующий объект mcpServers, не заменяя весь файл.

Шаг 2: Добавьте настройку локального клиента

Пример запуска открытого клиента без ключа:

{
  "mcpServers": {
    "atomno-fns-check": {
      "type": "stdio",
      "command": "uvx",
      "args": ["atomno-mcp-fns-check"]
    }
  }
}
  • Имя atomno-fns-check должно отличаться от других записей в вашем файле.
  • command — исполняемая команда. Если Cursor не находит uvx, укажите действительный полный путь к нему в своей системе.
  • args — аргументы команды. Здесь имя запускаемой команды совпадает с именем пакета; у других Python-пакетов это бывает иначе.
  • type: "stdio" задаёт локальное подключение через стандартные потоки процесса. Для него не нужен отдельный HTTP-сайт.

Синтаксически корректный JSON не проверяет существование программы, пакета и доступа к источнику.

Шаг 3: Ключ и совместимость размещённого режима

Для клиента, которому не нужен ключ, например открытого сценария с atomno-mcp-cbr-rates, этот шаг не требуется.

В инструкции от 7 октября 2026 была зафиксирована граница: опубликованная тогда версия atomno-mcp-fns-check 0.1.12 игнорировала MCP_FNS_API_KEY, а размещённый check_contractor был проверен в локальных исходниках 0.2.4. Это историческая проверка, а не утверждение о последнем опубликованном релизе сегодня.

Перед настройкой такого режима:

  1. Сверьте состав и ограничения продукта.
  2. Проверьте условие о совместимой версии и документацию фактически установленного клиента.
  3. Для предусмотренного подпиской режима используйте ключ из общего кабинета. Наличие ключа не делает несовместимый клиент совместимым и не переводит все его инструменты в размещённый режим.

Cursor поддерживает подстановку ${env:MCP_FNS_API_KEY} в поле env. Значение должно быть доступно процессу Cursor; сохраняйте конфигурацию команды без реальных ключей, а секрет задавайте в своей локальной среде. Не публикуйте токен в репозитории или диагностике. Само использование переменной окружения не ограничивает права процесса.

При подключении одного ключа в другие свои клиенты квота остаётся общей.

Шаг 4: Проверьте подключение

Найдите сервер в управлении MCP вашей версии Cursor — текущая документация описывает раздел Customize. Проверьте состояние и доступные инструменты. Если изменение файла не подхватилось, переподключите сервер средствами клиента; при необходимости полностью завершите и заново откройте Cursor, особенно после изменения PATH. Одного цвета индикатора недостаточно для вывода о доступности данных.

Типовые ошибки:

  • spawn uvx ENOENT — процесс не находит исполняемую команду; проверьте PATH или полный путь в command.
  • 401 Unauthorized — запрос не прошёл авторизацию. Проверьте нужный режим, ключ и права, не печатая секрет в лог.
  • Connection timeout — ответ не получен за отведённое время. По одному таймауту нельзя определить причину или утверждать, что данных в источнике нет.

Шаг 5: Вызовите понятный инструмент чтения

Откройте чат с агентом. Сначала просмотрите реально доступные инструменты и параметры, затем задайте запрос под один из них. Пример задачи для проверки компании: «Получить доступные сведения по указанному ИНН, показать источник, дату и ограничения ответа».

Проверьте последовательно:

  1. Клиент обнаружил инструменты сервера.
  2. Выбран ожидаемый инструмент с правильными параметрами; вызов подтверждён вами.
  3. Сервер вернул результат либо явную ошибку.
  4. Ответ модели не потерял источник и ограничения результата.

Не ожидайте заранее определённого имени инструмента или благополучной карточки компании. Для примера без ключа можно начать с курса валют по инструкции Cursor и проверить дату в ответе.

Что полезно для рабочего подключения

  • Не передавайте действующие ключи в проектном mcp.json. Для команды храните шаблон без секретов; проверьте, что именно попадает в Git.
  • Дополнительные параметры логирования берите из документации установленного сервера. Перед отправкой лога удалите секреты и персональные данные; универсального флага DEBUG у всех MCP нет.
  • Добавляйте следующие серверы после проверки первого. Время запуска зависит от пакетов, сети и системы — измерьте его у себя.
  • Кэш uv обслуживайте при конкретной проблеме по документации Astral; плановая очистка не является условием работы MCP.

Что дальше

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

Что проверить, если Cursor не находит uvx?

Проверьте установку uv и доступность uvx в PATH процесса Cursor. Если команда доступна в терминале, но не в редакторе, в поле command можно указать полный путь к uvx. После настройки полностью перезапустите Cursor.

Достаточно ли добавить ключ ФНС, чтобы включить размещённый режим?

Нет. Нужна версия клиента, которая поддерживает размещённый check_contractor. В статье отдельно указана проверка версии 0.1.12: она игнорирует MCP_FNS_API_KEY. Сверяйте условие о совместимой версии в инструкции Claude Desktop; сам пример конфигурации не подтверждает выпуск такого клиента.

Где хранить настройку MCP для команды?

Статья и инструкция Cursor различают глобальный файл и файл проекта. В общий репозиторий передавайте шаблон команды и аргументов без действующих ключей; секреты задавайте в своей локальной настройке.

С какого запроса начать знакомство с MCP в Cursor?

Для примера без ключа используйте курсы ЦБ по инструкции: попросите курс выбранной валюты и проверьте дату в ответе. Для другого источника сначала уточните необходимые переменные и доступный режим.

Нужно ли запускать MCP-сервер отдельным HTTP-сайтом для stdio?

Для показанного локального сценария Cursor запускает процесс по команде из конфигурации. Отдельный HTTP-сайт для этого не требуется; удалённый MCP и REST настраиваются иначе.

Как отличить проблему запуска от ошибки инструмента?

Сначала проверьте, появился ли сервер и его инструменты в клиенте. Ошибка поиска uvx относится к запуску процесса, а ошибка после вызова инструмента требует проверки его параметров, доступа и ответа источника.

Стоит ли сразу разрешать все вызовы без подтверждения?

Нет. Начните с понятной операции чтения. Изменение данных и списание денег требуют отдельного явного подтверждения; список инструментов следует просмотреть до выдачи разрешений.

Просмотр кода

Копируется исходный текст. Переносы меняют только отображение.

Текст

Поиск по сайту

Введите хотя бы два символа.

Tab — переход по ссылкам · Esc — закрыть