Как подключить Claude Code и Cursor к локальным MCP-серверам: пошаговое руководство

Локальный MCP-сервер это просто процесс, запущенный на вашей машине, с которым Claude Code или Cursor общается через stdin и stdout. Ни сети, ни авторизации, ни общей инфраструктуры. Это правильная стартовая точка, когда вы сами пишете сервер или подключаетесь к чему-то вроде локальной базы данных или файловой системы, которая имеет смысл только на вашей машине.

Вот как это реально настроить в обоих инструментах, где оно ломается и что на самом деле означают ошибки.

Что значит «локальный» в данном случае и почему это устроено именно так

Когда вы добавляете локальный (stdio) сервер, клиент запускает ваш сервер как дочерний процесс. Он пишет JSON-RPC запросы в stdin этого процесса и читает ответы из его stdout. Всё, что сервер логирует, идёт в stderr, который клиент перехватывает отдельно, чтобы не испортить поток JSON-RPC. Согласно официальной документации Claude Code, это рекомендованный транспорт для всего, что нужно запускать только на вашей машине, а HTTP оставлен для серверов, к которым должны обращаться другие люди или другие машины.

Важный компромисс: stdio-сервер существует только пока работает конкретно этот процесс, на конкретно этой машине. Поделиться работающим экземпляром с командой нельзя. Каждый разработчик, которому нужен тот же сервер, поднимает собственную копию.

Настройка в Claude Code

Зарегистрировать сервер:

claude mcp add --transport stdio my-server -- node my-server.js

У Claude Code есть три скоупа для этого, и выбор не того приводит к типичной путанице «почему коллега не видит этот сервер»:

• local (по умолчанию): хранится в ваших персональных настройках, ни с кем не расшарен.
• project (--scope project): записывается в файл .mcp.json в корне проекта, который вы коммитите в git, чтобы у всех в репозитории был одинаковый конфиг.
• user: доступен вам во всех проектах на вашей машине.

Есть деталь, на которой спотыкаются при переходе между собственными приложениями Claude: Claude Code требует явное поле "type": "stdio" в .mcp.json, тогда как Claude Desktop определяет stdio автоматически просто по наличию поля command. Скопировать рабочий конфиг из Claude Desktop прямо в .mcp.json Claude Code, не добавив это поле, это реальный и легко случающийся сбой.

Чтобы передать секреты или настройки в процесс сервера, используйте -e:

claude mcp add --transport stdio my-server -e API_KEY=your-key -- node my-server.js

Если вы используете --scope project, помните, что этот файл коммитится. Секреты держите в собственном окружении, а не в закоммиченном конфиге.

Настройка в Cursor

Cursor читает конфиг MCP из .cursor/mcp.json для проекта или ~/.cursor/mcp.json глобально. Не .vscode/mcp.json и не голый mcp.json в корне репозитория: оба варианта тупиковые, сервер не появится, и никакой ошибки, объясняющей почему, вы не увидите.

Самая частая причина сбоя здесь, согласно разбору проблем, который охватывает Cursor, VS Code и Claude Desktop, это не сломанная команда и не неверный путь. Это ключ верхнего уровня в JSON-файле. Cursor ожидает mcpServers. Устаревшее или опечатанное имя ключа даёт файл, который всё ещё валиден как JSON, поэтому Cursor не жалуется, он просто молча ничего не загружает.

Вторая по частоте причина, сам синтаксис JSON: висячая запятая после последнего сервера в списке или пропущенная запятая между двумя записями. Cursor и здесь не показывает ошибку парсинга в интерфейсе. Если сервер не появляется, а конфиг на вид в порядке, вставьте файл в любой JSON-валидатор, прежде чем трогать что-то ещё.

Ещё два пункта из того же разбора, которые стоит проверить перед тем, как считать сломанным сам сервер:

• Cursor думает, что корень воркспейса не там, где вы положили .cursor/mcp.json. Это чаще всего случается, когда вы открываете как воркспейс поддиректорию монорепозитория, а не его корень.
• Вы поправили конфиг, но не перезапустили IDE. Конфиг MCP в Cursor читается при старте, а не подхватывается на лету.

Короткие ответы на то, на чём реально застревают

Почему сервер не появляется, хотя я всё настроил правильно? Полностью перезапустите IDE. Уже это решает большинство случаев, которые выглядят как сломанный сервер, а на деле являются клиентом, который не перечитал конфиг.

Нужно ли перезапускать каждый раз при изменении конфига? Да, для обоих инструментов, это не опционально.

stdio или HTTP, что реально нужно? stdio для всего, что работает только на вашей машине (скрипт, локальная база для разработки). HTTP для всего, к чему должен обращаться коллега, CI-джоба или удалённый агент.

Можно просто направить всю команду на stdio-сервер, который крутится на моём ноутбуке? Нет. В stdio это в принципе не заложено, и MCP не пытается это обеспечить. Если команде нужен общий доступ к одному и тому же серверу, это сигнал строить (или подключаться к) HTTP-серверу, а не локальному.

Помимо Claude Code и Cursor

Claude Code и Cursor это MCP-хосты, но не единственные. Если вы экспериментируете вне этих инструментов, часто всплывают два проекта: Nanobot, самостоятельный self-hosted MCP-хост, который превращает набор MCP-серверов в агента, запускаемого вами самими, по умолчанию отдающего HTTP на localhost, без необходимости в IDE. iFlow CLI, терминальный кодинг-агент с собственным MCP-клиентом, нацеленный на тот же сценарий «направить агента на свой репозиторий», что и Claude Code, со своей экосистемой пакетов для установки MCP-инструментов. Ни один из них не заменяет Claude Code или Cursor для повседневной работы в IDE, но их стоит знать, если вы строите или тестируете MCP-сервер независимо от конкретного клиента.

Когда одного локального сервера на разработчика перестаёт хватать

В момент, когда команде нужно одно и то же состояние сервера на всех, или нужно знать, кто из коллег (или агентов) внёс конкретное изменение, stdio-сервер на чьём-то ноутбуке этого по конструкции не может. Это же тот момент, когда самостоятельно собирать авторизацию и контроль доступа поверх голого HTTP-сервера становится дорого. Как построить MCP-сервер для таск-трекера разбирает, что для этого реально нужно: токены со скоупом, рейт-лимиты, безопасная конкурентная запись.

Если вы не хотите строить этот слой самостоятельно, подключение Cursor или Claude Code к TAM даёт тот же опыт локальной настройки, только указывающий на сервер, которым уже пользуется вся ваша команда.