Установка MCP-сервера в Cursor: пошаговый гайд для 2026
Локальное подключение Python MCP-сервера в Cursor: установка uv, настройка mcp.json, проверка инструментов и разбор ошибок запуска и доступа.
- cursor
- tutorial
- mcp
- setup
В этой статье — локальное подключение 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. Это историческая проверка, а не утверждение о последнем опубликованном релизе сегодня.
Перед настройкой такого режима:
- Сверьте состав и ограничения продукта.
- Проверьте условие о совместимой версии и документацию фактически установленного клиента.
- Для предусмотренного подпиской режима используйте ключ из общего кабинета. Наличие ключа не делает несовместимый клиент совместимым и не переводит все его инструменты в размещённый режим.
Cursor поддерживает подстановку ${env:MCP_FNS_API_KEY} в поле env. Значение должно быть доступно процессу Cursor; сохраняйте конфигурацию команды без реальных ключей, а секрет задавайте в своей локальной среде. Не публикуйте токен в репозитории или диагностике. Само использование переменной окружения не ограничивает права процесса.
При подключении одного ключа в другие свои клиенты квота остаётся общей.
Шаг 4: Проверьте подключение
Найдите сервер в управлении MCP вашей версии Cursor — текущая документация описывает раздел Customize. Проверьте состояние и доступные инструменты. Если изменение файла не подхватилось, переподключите сервер средствами клиента; при необходимости полностью завершите и заново откройте Cursor, особенно после изменения PATH. Одного цвета индикатора недостаточно для вывода о доступности данных.
Типовые ошибки:
spawn uvx ENOENT— процесс не находит исполняемую команду; проверьте PATH или полный путь вcommand.401 Unauthorized— запрос не прошёл авторизацию. Проверьте нужный режим, ключ и права, не печатая секрет в лог.Connection timeout— ответ не получен за отведённое время. По одному таймауту нельзя определить причину или утверждать, что данных в источнике нет.
Шаг 5: Вызовите понятный инструмент чтения
Откройте чат с агентом. Сначала просмотрите реально доступные инструменты и параметры, затем задайте запрос под один из них. Пример задачи для проверки компании: «Получить доступные сведения по указанному ИНН, показать источник, дату и ограничения ответа».
Проверьте последовательно:
- Клиент обнаружил инструменты сервера.
- Выбран ожидаемый инструмент с правильными параметрами; вызов подтверждён вами.
- Сервер вернул результат либо явную ошибку.
- Ответ модели не потерял источник и ограничения результата.
Не ожидайте заранее определённого имени инструмента или благополучной карточки компании. Для примера без ключа можно начать с курса валют по инструкции Cursor и проверить дату в ответе.
Что полезно для рабочего подключения
- Не передавайте действующие ключи в проектном
mcp.json. Для команды храните шаблон без секретов; проверьте, что именно попадает в Git. - Дополнительные параметры логирования берите из документации установленного сервера. Перед отправкой лога удалите секреты и персональные данные; универсального флага DEBUG у всех MCP нет.
- Добавляйте следующие серверы после проверки первого. Время запуска зависит от пакетов, сети и системы — измерьте его у себя.
- Кэш
uvобслуживайте при конкретной проблеме по документации Astral; плановая очистка не является условием работы MCP.
Что дальше
- Каталог MCP — выбрать источник под следующую задачу.
- Claude Desktop setup — настройка другого клиента.
- Безопасность MCP — права и подтверждение действий перед рабочим использованием.
- Troubleshooting — дальнейший разбор ошибок.
Частые вопросы
Что проверить, если 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 относится к запуску процесса, а ошибка после вызова инструмента требует проверки его параметров, доступа и ответа источника.
Стоит ли сразу разрешать все вызовы без подтверждения?
Нет. Начните с понятной операции чтения. Изменение данных и списание денег требуют отдельного явного подтверждения; список инструментов следует просмотреть до выдачи разрешений.
