Если вы устали переключаться между терминалом, браузером и редактором, то MCP-серверы решают эту проблему. Они позволяют Claude Code самому читать документы в папке, подтягивать свежую документацию по библиотекам и работать с вашими файлами.
Расскажу, как добавить MCP в Claude Code, на примерах, которые сам использую каждый день. Без воды и лишних телодвижений.
Что такое MCP и зачем он нужен в Claude Code
MCP - это протокол, который связывает Claude с внешними инструментами и данными. Думайте о нем как о USB-порте для нейросети. Подключили файловую систему - Claude читает ваши документы. Подключили Context7 - и он знает актуальную документацию по любой библиотеке. Подключили базу данных - и Claude делает SQL-запросы прямо из чата.
Без MCP Claude Code работает в песочнице. Он видит только код в открытом проекте и то, что вы ему скормите. С MCP вы открываете ему доступ к внешнему миру. И это меняет всё.
В официальной документации подключение сводится к одной команде: claude mcp add. На практике же есть нюансы, о которые спотыкаются даже опытные разработчики.
Базовая команда добавления MCP-сервера
Всё начинается с синтаксиса. Базовая команда выглядит так:
claude mcp add <имя-сервера> <команда-запуска>
Первый аргумент - имя, под которым сервер появится в списке. Второй - команда, которая запускает ваш MCP-сервер. Например, если у вас есть Python-скрипт main.py, который запускается через uv, команда будет такой:
claude mcp add documents uv run main.py
Дальше всё зависит от того, какой сервер вы подключаете. Базовая команда уже есть.
Добавляем файловую систему: самый частый кейс
Чаще всего пользователи хотят дать Claude доступ к локальным файлам. Для этого существует готовый сервер @modelcontextprotocol/server-filesystem от Anthropic. Он запускается через npx, так что Node.js должен быть установлен.
Вот команда для macOS и Linux:
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Desktop
Разбор по частям. -s user указывает область действия - сервер будет доступен только вашему пользователю. Двойной дефис -- отделяет параметры самой команды от флагов claude. После него идёт запуск npx с сервером, а затем список папок, к которым нужно дать доступ. Можно указать несколько путей, разделяя их пробелом.
На Windows команда выглядит чуть иначе. Пути в кавычках, область действия через --scope user:
claude mcp add --scope user filesystem -- npx -y @modelcontextprotocol/server-filesystem "D:/Obsidian/Obsidian"
Обратите внимание: вместо ~/Documents здесь используется абсолютный путь с диском. И кавычки обязательны, если в пути есть пробелы.
После добавления обязательно проверьте, что сервер подключился:
claude mcp list
Если всё прошло успешно, вы увидите в списке файловую систему с указанными путями.
Три способа добавить MCP-сервер
Команда claude mcp add - не единственный вариант. В зависимости от ситуации удобно использовать конфигурационные файлы или настройку на уровне проекта. Разберу все три метода, чтобы вы выбирали под задачу.
Способ 1: через терминал - быстро и гибко
Первый способ мы уже частично разобрали. Терминал удобен, когда нужно быстро попробовать сервер или изменить настройки. Флаги позволяют задать область действия:
-s user- для текущего пользователя-s project- для проекта-s local- локальный режим (устаревший, но встречается)
Также можно указать транспорт: --transport stdio (стандартный ввод-вывод) или --transport sse для HTTP-серверов. По умолчанию используется stdio, и для большинства локальных серверов это правильно.
Пример с подключением своего скрипта:
claude mcp add --scope project --transport stdio qr -- python "D:\coding\Qr\qr.py"
Здесь мы подключаем Python-скрипт, который генерирует QR-коды. Обратите внимание на флаг --: после него команда запускается как есть.
Способ 2: через конфигурационный файл - для продвинутых
Если вам нужно прописать переменные окружения, сложные аргументы или шарить конфиг с коллегами, проще редактировать файл напрямую. Claude Code хранит MCP-серверы в JSON-файле. Найти его можно по адресу:
~/.claude.json (для user-скоупа) или .mcp.json в корне проекта (для project-скоупа).
Структура примерно такая:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "~/Documents"],
"env": {
"MY_TOKEN": "your-token"
}
}
}
}Для переменных окружения добавляется поле env. Это удобно, когда сервер требует токены или ключи API. Например, для GitHub-сервера с личным токеном. Замените your-token на реальный токен, иначе сервер не авторизуется.
Метод для тех, кто любит контролировать всё до мелочей. Но требует аккуратности: ошибка в JSON - и Claude Code может не запуститься. Поэтому я предпочитаю сначала использовать команду claude mcp add, а конфиг править только когда нужно что-то особенное.
Способ 3: на уровне проекта - для командной работы
Когда над проектом работает несколько человек, хочется, чтобы все использовали одинаковые MCP-серверы. Для этого подключайте их с флагом -s project.
Команда будет выглядеть так:
claude mcp add shared-tools -s project -- npx -y @your-team/mcp-tools
После такой команды конфиг сохраняется в .mcp.json в корне проекта. Этот файл можно закоммитить, и все разработчики автоматически получат те же серверы при работе с репозиторием.
Я рекомендую этот способ для стартапов и команд, где онбординг новых людей занимает много времени. Один раз настроили - и все работают с одинаковым инструментарием.
Управляем MCP-серверами: список, удаление, обновление
Со временем серверов становится много. Чтобы не запутаться, полезно знать команды управления.
Посмотреть все добавленные серверы:
claude mcp list
Удалить ненужный сервер:
claude mcp remove <имя-сервера>
Обновить сервер можно повторным запуском claude mcp add с тем же именем - старый конфиг перезапишется. Или отредактировать конфигурационный файл вручную.
MCP в Claude Code и Claude Desktop: в чём разница
Часто путают настройку MCP в Claude Code и в Claude Desktop. Это разные вещи, и способы подключения отличаются.
В Claude Desktop серверы добавляются через интерфейс: раздел Customize, затем Connectors, плюсик и Add custom connector. Там же можно настроить удалённый сервер по URL.
В Claude Code всё управление происходит через терминал. Файлы с локальными MCP-серверами тоже находятся в разных директориях. Не пытайтесь переносить конфиг из одного приложения в другое - скорее всего, пути и формат не совпадут.
Где брать готовые MCP-серверы
Не нужно писать свои серверы с нуля. Половина задач решается готовыми решениями. Вот несколько проверенных источников:
- Официальные серверы Anthropic в репозитории
modelcontextprotocol/serversна GitHub. Там есть файловая система, поиск, папки, память и другие. - Сервер Context7 - агрегатор актуальной документации по технологиям. Подключается через npx и отлично подходит для разработчиков, которым нужна свежая информация по библиотекам.
- Каталоги MCP-серверов на сайтах типа mcp.so или pulse.mcp.so. Там можно найти всё - от интеграций с базами данных до работы с почтой.
При выборе сервера смотрите на активность репозитория и звёзды. Заброшенные проекты могут содержать уязвимости или не работать с новыми версиями Claude Code.
Частые ошибки при добавлении MCP
На Reddit в обсуждениях разработчиков каждый второй вопрос - "почему у меня не работает MCP?". Причины обычно однотипные.
Ошибка 1: не перезапустили Claude Code. После добавления сервера нужно выйти из сессии и запустить её заново. Серверы подхватываются при старте. Это самый популярный источник недоразумений.
Ошибка 2: неправильные пути. Если вы скопировали команду с macOS на Windows или наоборот, пути почти наверняка не сработают. На Windows используйте двойные кавычки и путь с буквой диска. На Linux и macOS - абсолютные пути с тильдой для домашней директории.
Ошибка 3: нет Node.js или Python. Большинство серверов запускаются через npx или python. Проверьте, что они установлены и доступны в PATH. Можно проверить командой npx --version или python --version.
Ошибка 4: пакет ещё не скачан. npx при первом запуске скачивает пакет. Это занимает время. Иногда кажется, что сервер завис, но на самом деле идёт загрузка. Подождите или запустите команду без флага -y для интерактивного подтверждения.
Ошибка 5: конфликт портов. Если MCP-сервер использует SSE и уже занят порт, он не запустится. Проверьте свободные порты при подключении удалённых серверов.
Когда что-то не работает, первым делом запустите claude mcp list - он покажет статус сервера. Там видно, запущен ли сервер и нет ли ошибок.
MCP и токены: как не сжечь лимиты
Один из скрытых бонусов MCP - экономия токенов. Если вы дадите Claude доступ к папке с сотней файлов, он не будет читать их все подряд. Вместо этого он получит инструменты для просмотра списка файлов, чтения конкретных документов и поиска по содержимому. Такой подход расходует гораздо меньше токенов, чем попытка запихнуть всё в контекст.
Но всё же следите за лимитами. Инструменты MCP тоже тратят токены, особенно если вы запрашиваете содержимое больших файлов. Старайтесь давать Claude точные инструкции: какие папки смотреть, какие файлы читать. Это снижает расход и ускоряет ответ.
Работаем с флагманскими моделями из России
Claude Code становится по-настоящему полезным, когда вы подключаете к нему свежие модели и инструменты. Но тут есть нюанс для разработчиков из России. Стандартный доступ к Claude из РФ не работает, а с оплатой иностранной картой бывают проблемы.
Я пользуюсь сервисом 3GPT от 3SELLER - это роутер, который даёт доступ ко всем флагманским нейросетям из России. Там есть и Claude Fable 5, и Chat GPT 6, и Claude Opus 5.5, и даже генерация изображений. Оплата российской картой, через СБП или крипту - без иностранных карт.
С 3GPT можно создавать продающие тексты, делать сайты, обрабатывать изображения, генерировать видеоролики и голос. Внутри роутера несколько моделей, и вы переключаетесь между ними прямо в чате. Удобно, когда не хочется покупать подписку каждый сервис отдельно.
У них есть и готовые ИИ-агенты под конкретные задачи. Выбираете агента, меняете модель в чате - и работаете. Не нужно самому настраивать промпты и писать код.
Если вы плотно работаете с нейросетями из России, присмотритесь к 3GPT. За 149 рублей вы получаете доступ к нескольким топовым моделям, и это сильно упрощает жизнь.
Практический шаг: попробуйте прямо сейчас
Не откладывайте на потом. Откройте терминал и выполните:
- Создайте тестовую папку с несколькими документами.
- Подключите filesystem-сервер командой из начала статьи, указав путь к этой папке.
- Перезапустите Claude Code и попросите его найти определённую фразу в файлах.
- Посмотрите, как Claude отвечает, имея доступ к данным.
Это займёт у вас не больше десяти минут. Зато после вы почувствуете, что такое работа с MCP в полную силу.
А если появятся вопросы - пишите, обсудим. Удачи с автоматизацией.