Настройка MCP-серверов: Расширение возможностей интеграции Claude Code с внешними сервисами

Чему вы научитесь

Понимать, что такое MCP и как он расширяет возможности Claude Code
Выбирать подходящие сервисы из 15 предустановленных MCP-серверов для вашего проекта
Правильно настраивать API-ключи и переменные окружения
Оптимизировать использование MCP, избегая перегрузки контекстного окна

Текущая проблема

По умолчанию Claude Code имеет только возможности работы с файлами и выполнения команд, но вам может понадобиться:

Запрашивать PR и Issues на GitHub
Парсить веб-страницы
Работать с базой данных Supabase
Запрашивать актуальную документацию
Сохранять память между сессиями

Если выполнять эти задачи вручную, придётся постоянно переключаться между инструментами и копировать данные — это неэффективно. MCP-серверы (Model Context Protocol) помогут автоматизировать интеграцию с внешними сервисами.

Когда использовать этот подход

Ситуации, подходящие для использования MCP-серверов:

Проект связан со сторонними сервисами: GitHub, Vercel, Supabase и др.
Требуется запрашивать актуальную документацию (Cloudflare, ClickHouse)
Нужно сохранять состояние или память между сессиями
Требуется парсинг веб-страниц или генерация UI-компонентов

Ситуации, когда MCP не нужен:

Работа только с локальными файлами
Чистая фронтенд-разработка без интеграции с внешними сервисами
Простые CRUD-приложения с минимальной работой с базой данных

🎒 Подготовка перед началом

Перед настройкой убедитесь:

Предварительная проверка

✅ Завершена установка плагина
✅ Знакомы с базовым синтаксисом JSON-конфигурации
✅ Есть API-ключи для нужных сервисов (GitHub PAT, Firecrawl API Key и др.)
✅ Знаете расположение конфигурационного файла ~/.claude.json

Основная концепция

Что такое MCP

MCP (Model Context Protocol) — это протокол, который Claude Code использует для подключения к внешним сервисам. Он позволяет ИИ получать доступ к GitHub, базам данных, запросам документации и другим внешним ресурсам, расширяя его возможности.

Принцип работы:

Claude Code ←→ MCP Server ←→ External Service
  (локально)    (посредник)     (GitHub/Supabase/...)

Структура конфигурации MCP

Каждая конфигурация MCP-сервера содержит:

json

{
  "mcpServers": {
    "server-name": {
      "command": "npx",          // команда запуска
      "args": ["-y", "package"],  // аргументы команды
      "env": {                   // переменные окружения
        "API_KEY": "YOUR_KEY"
      },
      "description": "Описание функционала"   // описание
    }
  }
}

Типы:

npx-тип: запуск через npm-пакет (GitHub, Firecrawl)
http-тип: подключение к HTTP-эндпоинту (Vercel, Cloudflare)

Управление контекстным окном (Важно!)

Предупреждение о контексте

Каждый включённый MCP-сервер занимает часть контекстного окна. При включении слишком многих серверов контекст в 200K может сократиться до 70K.

Золотое правило:

Настройте 20-30 MCP-серверов (все доступны)
Для каждого проекта включайте < 10
Общее количество активных инструментов < 80

Используйте disabledMcpServers в конфигурации проекта для отключения ненужных MCP.

Пошаговая инструкция

Шаг 1: Просмотр доступных MCP-серверов

Everything Claude Code предоставляет 15 предустановленных MCP-серверов:

MCP-сервер	Тип	Требуется ключ	Назначение
github	npx	✅ GitHub PAT	Операции с PR, Issues, репозиториями
firecrawl	npx	✅ API Key	Парсинг и краулинг веб-страниц
supabase	npx	✅ Project Ref	Операции с базой данных
memory	npx	❌	Сохранение памяти между сессиями
sequential-thinking	npx	❌	Улучшение цепочечного рассуждения
vercel	http	❌	Деплой и управление проектами
railway	npx	❌	Деплой на Railway
cloudflare-docs	http	❌	Поиск по документации
cloudflare-workers-builds	http	❌	Сборка Workers
cloudflare-workers-bindings	http	❌	Привязки Workers
cloudflare-observability	http	❌	Логи и мониторинг
clickhouse	http	❌	Аналитические запросы
context7	npx	❌	Поиск актуальной документации
magic	npx	❌	Генерация UI-компонентов
filesystem	npx	❌ (нужен путь)	Операции с файловой системой

Ожидаемый результат: Полный список из 15 MCP-серверов, охватывающих GitHub, деплой, базы данных, запросы документации и другие распространённые сценарии.

Шаг 2: Копирование конфигурации MCP в Claude Code

Скопируйте конфигурацию из директории исходников:

bash

# Копирование шаблона конфигурации MCP
cp source/affaan-m/everything-claude-code/mcp-configs/mcp-servers.json ~/.claude/mcp-servers-backup.json

Зачем: Резервное копирование исходной конфигурации для последующего сравнения.

Шаг 3: Выбор нужных MCP-серверов

Выберите MCP-серверы в соответствии с потребностями вашего проекта.

Примеры сценариев:

Тип проекта	Рекомендуемые MCP
Fullstack-приложение (GitHub + Supabase + Vercel)	github, supabase, vercel, memory, context7
Фронтенд-проект (Vercel + запросы документации)	vercel, cloudflare-docs, context7, magic
Проект с данными (ClickHouse + аналитика)	clickhouse, sequential-thinking, memory
Общая разработка	github, filesystem, memory, context7

Ожидаемый результат: Чёткое соответствие типов проектов и MCP-серверов.

Шаг 4: Редактирование конфигурационного файла `~/.claude.json`

Откройте конфигурационный файл Claude Code:

macOS/LinuxWindows

bash

vim ~/.claude.json

powershell

notepad $env:USERPROFILE\.claude.json

Добавьте раздел mcpServers в ~/.claude.json:

json

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT_HERE"
      },
      "description": "GitHub operations - PRs, issues, repos"
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"],
      "description": "Persistent memory across sessions"
    },
    "context7": {
      "command": "npx",
      "args": ["-y", "@context7/mcp-server"],
      "description": "Live documentation lookup"
    }
  }
}

Зачем: Это основная конфигурация, которая указывает Claude Code, какие MCP-серверы запускать.

Ожидаемый результат: Объект mcpServers содержит конфигурации выбранных вами MCP-серверов.

Шаг 5: Замена плейсхолдеров API-ключей

Для MCP-серверов, требующих API-ключи, замените плейсхолдеры YOUR_*_HERE:

Пример для GitHub MCP:

Сгенерируйте GitHub Personal Access Token:
- Перейдите на https://github.com/settings/tokens
- Создайте новый токен с правами repo
Замените плейсхолдер в конфигурации:

json

{
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  // замените на реальный токен
  }
}

Другие MCP, требующие ключи:

MCP	Название ключа	Где получить
firecrawl	FIRECRAWL_API_KEY	https://www.firecrawl.dev/
supabase	--project-ref	https://supabase.com/dashboard

Зачем: Без реальных ключей MCP-серверы не смогут подключиться к внешним сервисам.

Ожидаемый результат: Все плейсхолдеры YOUR_*_HERE заменены на реальные ключи.

Шаг 6: Настройка отключения MCP на уровне проекта (Рекомендуется)

Чтобы не включать все MCP для всех проектов, создайте .claude/config.json в корне проекта:

json

{
  "disabledMcpServers": [
    "supabase",      // отключить ненужные MCP
    "railway",
    "firecrawl"
  ]
}

Зачем: Это позволяет гибко управлять активными MCP на уровне проекта, избегая перегрузки контекстного окна.

Ожидаемый результат: Файл .claude/config.json содержит массив disabledMcpServers.

Шаг 7: Перезапуск Claude Code

Перезапустите Claude Code для применения конфигурации:

bash

# Остановите Claude Code (если запущен)
# Затем запустите снова
claude

Зачем: Конфигурация MCP загружается при запуске, поэтому требуется перезапуск.

Ожидаемый результат: После запуска Claude Code MCP-серверы загружаются автоматически.

Контрольная точка ✅

Проверьте успешность настройки MCP:

Проверка статуса загрузки MCP:

Введите в Claude Code:

bash

/tool list

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

Тестирование функционала MCP:

Если вы включили GitHub MCP, протестируйте запрос:

bash

# Запрос GitHub Issues
@mcp list issues

Ожидаемый результат: Возвращается список Issues вашего репозитория.

Проверка контекстного окна:

Проверьте количество инструментов в ~/.claude.json:

bash

jq '.mcpServers | length' ~/.claude.json

Ожидаемый результат: Количество включённых MCP-серверов < 10.

Совет по отладке

Если MCP не загрузился, проверьте лог-файлы Claude Code:

macOS/Linux: ~/.claude/logs/
Windows: %USERPROFILE%\.claude\logs\

Типичные ошибки

Ошибка 1: Слишком много MCP — недостаточно контекста

Симптомы: В начале диалога контекстное окно составляет только 70K вместо 200K.

Причина: Каждый включённый инструмент MCP занимает часть контекстного окна.

Решение:

Проверьте количество включённых MCP (~/.claude.json)
Используйте disabledMcpServers на уровне проекта для отключения ненужных MCP
Держите общее количество активных инструментов < 80

Ошибка 2: API-ключи не настроены правильно

Симптомы: При вызове функций MCP появляется ошибка прав доступа или сбой подключения.

Причина: Плейсхолдеры YOUR_*_HERE не заменены.

Решение:

Проверьте поле env в ~/.claude.json
Убедитесь, что все плейсхолдеры заменены на реальные ключи
Проверьте, что у ключей достаточно прав (например, GitHub Token требует права repo)

Ошибка 3: Неверный путь в Filesystem MCP

Симптомы: Filesystem MCP не может получить доступ к указанной директории.

Причина: Путь в args не заменён на реальный.

Решение:

json

{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"],  // замените на ваш путь к проектам
    "description": "Filesystem operations"
  }
}

Ошибка 4: Конфигурация на уровне проекта не применяется

Симптомы: disabledMcpServers в корне проекта не отключает MCP.

Причина: Неверный путь или формат .claude/config.json.

Решение:

Убедитесь, что файл находится в корне проекта: .claude/config.json
Проверьте корректность JSON-формата (используйте jq . для проверки)
Убедитесь, что disabledMcpServers — это массив строк

Итоги урока

В этом уроке мы изучили методы настройки MCP-серверов:

Ключевые моменты:

MCP расширяет возможности интеграции Claude Code с внешними сервисами
Выбирайте подходящие серверы из 15 предустановленных MCP (рекомендуется < 10)
Замените плейсхолдеры YOUR_*_HERE на реальные API-ключи
Используйте disabledMcpServers на уровне проекта для контроля количества включённых серверов
Держите общее количество активных инструментов < 80, чтобы избежать перегрузки контекстного окна

Следующий шаг: Вы настроили MCP-серверы, в следующем уроке изучим основные Commands.

Анонс следующего урока

В следующем уроке мы изучим Подробный обзор основных Commands.
Вы узнаете:
Функции и сценарии использования 14 slash-команд
Как команда /plan создаёт план реализации
Как команда /tdd выполняет разработку через тестирование
Как быстро запускать сложные рабочие процессы с помощью команд

Приложение: Справка по исходному коду

Нажмите, чтобы посмотреть расположение исходного кода

Дата обновления: 2026-01-25

Функционал	Путь к файлу	Строки
Шаблон конфигурации MCP	`mcp-configs/mcp-servers.json`	1-92
Важные примечания README	`README.md`	348-369

Ключевые конфигурации:

15 MCP-серверов (GitHub, Firecrawl, Supabase, Memory, Sequential-thinking, Vercel, Railway, серия Cloudflare, ClickHouse, Context7, Magic, Filesystem)
Поддержка двух типов: npx (командная строка) и http (подключение к эндпоинту)
Использование disabledMcpServers для контроля количества включённых серверов на уровне проекта

Ключевые правила:

Настройте 20-30 MCP-серверов
Для каждого проекта включайте < 10
Общее количество активных инструментов < 80
Риск сокращения контекстного окна с 200K до 70K

Настройка MCP-серверов: Расширение возможностей интеграции Claude Code с внешними сервисами ​

Чему вы научитесь ​

Текущая проблема ​

Когда использовать этот подход ​

🎒 Подготовка перед началом ​

Основная концепция ​

Что такое MCP ​

Структура конфигурации MCP ​

Управление контекстным окном (Важно!) ​

Пошаговая инструкция ​

Шаг 1: Просмотр доступных MCP-серверов ​

Шаг 2: Копирование конфигурации MCP в Claude Code ​

Шаг 3: Выбор нужных MCP-серверов ​

Шаг 4: Редактирование конфигурационного файла ~/.claude.json ​

Шаг 5: Замена плейсхолдеров API-ключей ​

Шаг 6: Настройка отключения MCP на уровне проекта (Рекомендуется) ​

Шаг 7: Перезапуск Claude Code ​

Контрольная точка ✅ ​

Типичные ошибки ​

Ошибка 1: Слишком много MCP — недостаточно контекста ​

Ошибка 2: API-ключи не настроены правильно ​

Ошибка 3: Неверный путь в Filesystem MCP ​

Ошибка 4: Конфигурация на уровне проекта не применяется ​

Итоги урока ​

Анонс следующего урока ​

Приложение: Справка по исходному коду ​

Настройка MCP-серверов: Расширение возможностей интеграции Claude Code с внешними сервисами

Чему вы научитесь

Текущая проблема

Когда использовать этот подход

🎒 Подготовка перед началом

Основная концепция

Что такое MCP

Структура конфигурации MCP

Управление контекстным окном (Важно!)

Пошаговая инструкция

Шаг 1: Просмотр доступных MCP-серверов

Шаг 2: Копирование конфигурации MCP в Claude Code

Шаг 3: Выбор нужных MCP-серверов

Шаг 4: Редактирование конфигурационного файла `~/.claude.json`

Шаг 5: Замена плейсхолдеров API-ключей

Шаг 6: Настройка отключения MCP на уровне проекта (Рекомендуется)

Шаг 7: Перезапуск Claude Code

Контрольная точка ✅

Типичные ошибки

Ошибка 1: Слишком много MCP — недостаточно контекста

Ошибка 2: API-ключи не настроены правильно

Ошибка 3: Неверный путь в Filesystem MCP

Ошибка 4: Конфигурация на уровне проекта не применяется

Итоги урока

Анонс следующего урока

Приложение: Справка по исходному коду