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

MAATRIX

Приложение Claude Desktop стоит, чат работает, но модель по-прежнему не видит ваши файлы, не может заглянуть в базу данных и ничего не знает про содержимое папки на диске — потому что сама по себе она этого и не умеет. Всё это добавляют MCP-серверы, а вот как их физически подключить к приложению, из интерфейса не понятно вообще: нет ни кнопки «добавить сервер», ни визарда — только текстовый конфиг, который нужно найти и отредактировать руками. Дальше — пошаговый гайд: где лежит конфиг на macOS и Windows, как выглядит его структура, как подключить готовый сервер из документации MCP и что делать, если после перезапуска инструменты так и не появились. Если коротко: MCP (Model Context Protocol) — открытый протокол, по которому приложение вроде Claude Desktop запускает рядом отдельный процесс-сервер и разговаривает с ним по JSON-RPC, получая доступ к его инструментам, ресурсам и промптам. Сервер файловой системы даёт модели читать и писать файлы в разрешённой папке, сервер базы данных — выполнять SQL-запросы, сервер поисковика — ходить в интернет. Само приложение Claude Desktop умеет только один транспорт для локальных серверов — stdio, то есть запуск процесса напрямую на вашей машине; про то, что это такое и чем отличается от сетевых вариантов, подробнее в статье что такое MCP простыми словами. Здесь — только практика подключения.

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

Три вещи, без которых дальше не имеет смысла идти.

Установленное приложение Claude Desktop. Речь именно про десктопное приложение для macOS или Windows, а не про веб-версию claude.ai в браузере — там конфигов и MCP-серверов нет вообще, это функциональность только приложения. Проверить версию можно в меню приложения (на macOS — Claude → About Claude, на Windows — через меню с тремя точками в правом верхнем углу); MCP поддерживается уже давно, но если приложение не обновлялось месяцами, сначала обновите его.

Node.js или Python — в зависимости от того, какой сервер подключаете. Большинство готовых MCP-серверов из документации и открытых репозиториев написаны либо на JavaScript и запускаются командой npx, либо на Python и запускаются через uvx или python. Для npx-серверов нужен установленный Node.js (LTS-версия, node --version должен показывать 18.x или новее), для Python-серверов — сам Python 3.10+ и желательно uv — быстрый менеджер пакетов, который uvx использует под капотом. Проверить, что Node.js вообще на месте:

node --version
npm --version
npx --version

Если команда не найдена — ставьте Node.js с официального сайта nodejs.org, отдельная инструкция здесь не нужна, установщик доводит всё сам.

Понимание, к какой папке или базе вы дадите доступ. MCP-сервер файловой системы получает в конфиге конкретный путь и работает только с ним — заранее решите, что именно должно быть видно модели, и не указывайте в качестве пути весь диск целиком.

Где находится конфиг Claude Desktop

Всё управление MCP-серверами в приложении сводится к одному JSON-файлу — claude_desktop_config.json. Никакого графического интерфейса для его редактирования нет: файл открывается в обычном текстовом редакторе.

Быстрее всего найти его через само приложение: Settings → Developer → Edit Config (на некоторых версиях пункт называется просто Developer Settings). Кнопка либо откроет файл в редакторе по умолчанию, либо покажет его в файловом менеджере — этого обычно достаточно, чтобы не искать путь руками.

Если нужно найти файл напрямую, пути такие:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

На Windows проще всего вставить %APPDATA%\Claude\claude_desktop_config.json прямо в адресную строку проводника — переменная окружения развернётся автоматически. На macOS путь скрытый (папка Library спрятана по умолчанию), поэтому в Finder удобнее нажать Cmd+Shift+G и вставить путь целиком, либо открыть файл через терминал:

open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

Если файла ещё нет — это нормально, значит MCP-серверы в приложении пока не настраивались. Создайте его вручную в этой же папке с содержимым из следующего раздела; папка Claude при этом уже должна существовать (она появляется после первого запуска приложения).

Структура конфига: секция mcpServers

Конфиг Claude Desktop — обычный JSON с одним ключом верхнего уровня, который вас интересует, — mcpServers. Внутри — объект, где каждый ключ — произвольное имя сервера (то, как он будет подписан в интерфейсе), а значение описывает, как его запустить:

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

Разбор полей:

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

Важная деталь про command: приложение Claude Desktop на macOS запускается не из терминала, а из Finder или Launchpad, поэтому оно не наследует ваш PATH из shell-профиля. Если npx установлен через nvm или другой менеджер версий и в системном PATH не виден, приложение не найдёт команду, даже если в терминале всё работает. Обходится это либо прописыванием полного пути к бинарнику (/usr/local/bin/npx или результат команды which npx), либо установкой Node.js через официальный установщик, который кладёт бинарники в стандартные системные пути.

Пример с уже подставленным сервером (файловая система, доступ только к одной папке):

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

Если серверов несколько, они просто перечисляются рядом внутри того же объекта mcpServers — через запятую, каждый со своим ключом-именем.

Установка готового сервера: официальный сервер файловой системы

Проще всего начать с официального сервера файловой системы из документации MCP — он не требует токенов, ключей API и внешних сервисов, только путь к папке на диске. Это хороший первый сервер, чтобы убедиться, что вся цепочка «конфиг → запуск процесса → инструмент в интерфейсе» работает, прежде чем подключать что-то со своими секретами.

Устанавливать его отдельно не нужно: команда npx -y сама скачивает пакет при первом запуске и кеширует его локально, повторные запуски идут уже из кеша. Проверить, что пакет вообще запускается, можно прямо в терминале до того, как трогать конфиг приложения:

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

Если команда в терминале зависает без ошибок (это нормальное поведение — сервер ждёт подключения по stdio и не пишет ничего в консоль) или молча завершается без вывода — значит пакет скачался и в принципе способен стартовать. Остановите его Ctrl+C и переходите к конфигу: впишите блок из предыдущего раздела в claude_desktop_config.json, подставив свой реальный путь к папке вместо /Users/имя/Documents/projects (на Windows путь будет вида C:\\Users\\имя\\Documents\\projects — обратные слэши нужно экранировать двойными).

Для Python-серверов из документации MCP команда обычно выглядит похоже, только вместо npx — uvx:

{
  "mcpServers": {
    "имя-сервера": {
      "command": "uvx",
      "args": ["имя-пакета-сервера"]
    }
  }
}

Точное имя пакета и набор аргументов для конкретного сервера всегда смотрите в его собственной документации — они отличаются от сервера к серверу, и переносить пример один в один без проверки не стоит.

Перезапуск Claude Desktop и проверка подключения

После сохранения claude_desktop_config.json приложение нужно полностью перезапустить — просто закрыть окно недостаточно, оно сворачивается в фоновый процесс. На macOS: Claude в строке меню → Quit Claude (или Cmd+Q), затем запустить снова. На Windows: через системный трей найти иконку приложения, выйти полностью, затем запустить заново.

Если конфиг подхватился и сервер запустился успешно, в интерфейсе чата появляется индикатор доступных инструментов — обычно значок в виде плитки или молотка рядом с полем ввода сообщения. При клике на него открывается список подключённых MCP-серверов и инструментов, которые они предоставляют: для сервера файловой системы это будут пункты вроде чтения файла, записи файла, листинга директории.

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

Логи самого приложения по MCP-серверам лежат отдельно от общих логов и обновляются при каждой попытке запуска:

macOS:

~/Library/Logs/Claude/mcp*.log

Windows:

%APPDATA%\Claude\logs\mcp*.log

Там же видно stderr процесса сервера — если сервер сам упал с ошибкой (не найден путь, не хватает переменной окружения, конфликт версий), текст ошибки почти всегда там.

Типичные проблемы при подключении

Сервер не запускается: неверный путь в args. Самая частая причина. Опечатка в пути к папке, путь на Windows без экранированных слэшей (C:\Users\... вместо C:\\Users\\...), путь к несуществующей директории — сервер файловой системы просто откажется стартовать. Проверяйте JSON целиком в любом онлайн-валидаторе перед сохранением: одна лишняя или недостающая запятая ломает весь файл, и тогда не запустится вообще ни один сервер, даже те, что были настроены раньше и работали.

Права доступа к папке. Если папка, указанная в args, защищена системными ограничениями доступа (на macOS это может быть, например, папка внутри iCloud Drive или системный каталог, требующий отдельного разрешения в Privacy & Security), процесс сервера стартует, но операции чтения или записи будут падать с ошибкой доступа уже во время использования, а не при запуске. На macOS первым делом проверяйте System Settings → Privacy & Security → Files and Folders — само приложение Claude там может не значиться, тогда доступ дают тому процессу, который реально лезет в файлы.

Конфликт версий Node.js. Если на машине установлено несколько версий Node.js через nvm, fnm или похожий менеджер, npx в системном PATH может указывать не на ту версию, с которой тестировался сервер. Симптом — сервер запускается в терминале от вашего пользователя, но не запускается из-под Claude Desktop, потому что приложение видит другой (или вообще пустой) PATH. Решение то же, что и с ненайденной командой выше: прописать в command абсолютный путь к нужному бинарнику npx, полученный командой which npx (macOS) или where npx (Windows), вместо голого имени команды.

JSON битый, но приложение не говорит почему. Claude Desktop не всегда явно сообщает об ошибке синтаксиса в конфиге — иногда просто молча стартует без единого сервера. Если после правки конфига пропали даже ранее рабочие серверы — в 90% случаев дело в синтаксисе: пропущенная скобка, лишняя запятая после последнего элемента массива или объекта, незакрытая кавычка.

Сервер требует переменную окружения, а её нет. Серверы, которые ходят во внешние API (поиск, календарь, таск-трекер), почти всегда требуют токен в блоке env. Забытая или неверно вставленная переменная — сервер либо не стартует, либо стартует, но каждый вызов инструмента заканчивается ошибкой авторизации. Значение в env — это именно значение, без кавычек внутри самой строки токена и без пробелов по краям.

Если сервер нужен не только локально: перенос на свою инфраструктуру

Всё, что описано выше, — про stdio: конфиг Claude Desktop запускает процесс сервера локально на той же машине, где стоит приложение. Это удобно для личного использования, но не масштабируется дальше одного компьютера: серверу с секретами и настройками придётся жить в конфиге на каждой машине отдельно, а поделиться доступом с коллегой означает передать ему все токены в открытом виде.

Если MCP-сервер должен быть доступен постоянно, с нескольких устройств, или его использует не один человек, — логичный шаг вынести его на собственный VPS и превратить из локального stdio-процесса в сетевой сервис поверх HTTP или SSE. Это более сложный сценарий: понадобится не просто исполняемый файл в конфиге, а сервер, слушающий порт, обратный прокси перед ним (nginx или Caddy с правильными заголовками для потокового ответа) и авторизация, потому что сетевой эндпоинт — уже не приватный процесс на вашем ноутбуке, а адрес, до которого может дотянуться кто угодно, если не закрыть его токеном. Здесь эта тема раскрыта только на уровне идеи, подробный разбор транспортов, конфигов Docker и настройки прокси — в статье как поднять MCP-сервер на VPS, а частые ошибки уже поднятого сетевого сервера — в статье MCP-сервер на сервере: частые ошибки и решения.

Если решите переносить сервер на свою инфраструктуру, под сам сервер отдельная мощная машина не нужна: MCP-сервер в основном ждёт ответа от внешних API и почти не нагружает процессор, поэтому небольшого VPS с парой ядер и парой гигабайт памяти достаточно и для нескольких обёрнутых серверов сразу.

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