Skip to main content
Все гайды
Содержание гайда

Содержание гайда

Время на изучение: 12 мин
#automation#mcp#claude-code#typescript#devtools
Средний12 мин

MCP Servers и Claude Code: практическое руководство по подключению и разработке

Как расширить возможности Claude Code с помощью Model Context Protocol: подключение файловой системы, GitHub, PostgreSQL, Brave Search и создание собственного сервера на TypeScript.

Опубликовано:

Claude Code «из коробки» уже умеет читать локальные файлы, выполнять команды в терминале и редактировать исходный код проекта. Однако в реальной разработке этого часто недостаточно: требуется извлечь данные из базы PostgreSQL, проверить открытые Pull Requests на GitHub, подтянуть актуальную документацию или сделать запрос к внутреннему корпоративному API.

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

В этом практическом руководстве мы разберём архитектуру MCP, научимся подключать официальные готовые серверы, напишем собственный сервер на TypeScript и закрепим знания на практических задачах.

1. Что такое MCP Server

Model Context Protocol (MCP) — открытый протокол коммуникации, разработанный компанией Anthropic, который стандартизирует взаимодействие между большими языковыми моделями (LLM) и внешними инструментами или источниками данных.

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

text
┌─────────────────────────────────────────────────────────────┐ │ Claude Code (Клиент) │ └──────────────────────────────┬──────────────────────────────┘ │ JSON-RPC 2.0 (stdio / SSE) ▼ ┌─────────────────────────────────────────────────────────────┐ │ MCP Server (Адаптер) │ └──────┬───────────────────────┼───────────────────────┬──────┘ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ Файловая │ │ GitHub API │ │ База данных │ │ система │ │ и Issues │ │ PostgreSQL │ └─────────────┘ └─────────────┘ └─────────────┘

Любой MCP Server предоставляет модели три базовых примитива:

  • Tools (Инструменты) — исполняемые функции с типизированной JSON-схемой параметров, которые Claude Code может вызывать в процессе решения задачи (например, create_issue, execute_query).
  • Resources (Ресурсы) — пассивные данные или схемы, которые ассистент считывает в качестве входного контекста (файлы, схемы БД, логи).
  • Prompts (Шаблоны промптов) — преднастроенные сценарии, упрощающие типовые повторяющиеся задачи.

Сравнение возможностей Claude Code

СценарийБез MCP (базовый Claude Code)С подключенными MCP Servers
Работа с файламиТолько внутри текущей директории проектаДоступ к любым разрешённым папкам и заметкам
Данные репозиторияЛокальные файлы через git diff / git logЧтение issues, PR, code review и API GitHub
Базы данныхТолько при наличии локального CLI-клиентаПрямой анализ схемы, просмотр таблиц и выполнение SQL
Поиск информацииЛокальный поиск через grep / ripgrepАктуальный веб-поиск в реальном времени через Brave
Внутренние сервисыНедоступны без сложных bash-скриптовВызов методов внутренних микросервисов через SDK

2. Архитектура и принцип работы MCP

Архитектура взаимодействия построена на стандарте JSON-RPC 2.0. В большинстве локальных сценариев обмен данными происходит через стандартные потоки ввода/вывода (stdio), а для удалённых серверов — через Server-Sent Events (SSE) или HTTP.

Пошаговый жизненный цикл запроса

  1. Инициализация и Handshake: При запуске Claude Code считывает конфигурацию, запускает процессы серверов и запрашивает перечень инструментов (tools/list).
  2. Публикация возможностей: Сервер возвращает методы с JSON-схемами параметров и описанием их назначения.
  3. Оценка намерения: При вводе запроса на естественном языке Claude сопоставляет задачу с зарегистрированными инструментами.
  4. Вызов инструмента: Если для решения требуются внешние данные, модель отправляет структурированный запрос tools/call серверу с валидными аргументами.
  5. Выполнение сервером: Сервер связывается с внешней БД, API или файловой системой и передаёт сырой результат клиенту.
  6. Синтез ответа: Claude интерпретирует полученные данные и формирует итоговый структурированный ответ.
Примечание

Взаимодействие прозрачно для разработчика: не нужно вручную помнить параметры методов или синтаксис API. Claude выбирает подходящий инструмент автономно на основе контекста.

3. Как подключить MCP Server к Claude Code

Серверы подключаются через JSON-конфигурацию в секции mcpServers. Claude Code поддерживает два уровня конфигурации:

  1. Конфигурация проекта (.claude/settings.json) — действует исключительно в рамках текущей папки и может безопасно храниться в репозитории для всей команды.
  2. Глобальная конфигурация (~/.claude/settings.json) — доступна для всех проектов текущего пользователя в операционной системе.
json
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropic-ai/mcp-filesystem",
        "./docs"
      ]
    }
  }
}

Параметры конфигурации

Каждая запись сервера в mcpServers состоит из трёх ключевых полей:

ПараметрТипОбязательныйОписание и назначениеПримеры значений
commandstringДаИсполняемая команда запуска процесса сервера"npx", "node", "uvx", "docker"
argsstring[]ДаМассив аргументов запуска (имя пакета, пути, флаги)["-y", "@anthropic-ai/mcp-filesystem", "/path"]
envobjectНетПеременные окружения для авторизации и API-ключей{"GITHUB_TOKEN": "ghp_...", "DEBUG": "1"}
Совет

Если вы используете MCP-серверы на Python, вместо npx можно применять uvx: "command": "uvx", "args": ["mcp-server-git"].

4. Каталог готовых MCP Servers

Официальные и проверенные сообществом серверы закрывают большинство типичных задач разработчика:

СерверОфициальный пакетДоступ / АутентификацияОсновные возможности
Filesystem@anthropic-ai/mcp-filesystemПути к разрешённым локальным папкамЧтение, запись и поиск в каталогах вне корня проекта
GitHub@anthropic-ai/mcp-githubPersonal Access Token (GITHUB_TOKEN)Поиск по репозиториям, анализ issues, ревью PR
PostgreSQL@anthropic-ai/mcp-postgresСтрока подключения (connectionString)Чтение схемы, просмотр таблиц, выполнение SQL
Brave Search@anthropic-ai/mcp-brave-searchAPI-ключ поиска (BRAVE_API_KEY)Свежая информация из интернета без галлюцинаций

1. Filesystem Server

Предоставляет Claude доступ к каталогам за пределами текущего проекта (например, к базе знаний Obsidian):

json
{ "mcpServers": { "docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/Users/username/Developer/knowledge-base" ] } } }

2. GitHub Server

Позволяет напрямую взаимодействовать с задачами, PR и репозиториями организации:

json
{ "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" } } } }

3. PostgreSQL Server

Даёт возможность выполнять аналитические и диагностические SQL-запросы к базе данных:

json
{ "mcpServers": { "postgres": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-postgres", "postgresql://postgres:password@localhost:5432/my_app_db" ] } } }

4. Brave Search Server

Интегрирует поисковый движок для проверки свежей документации, changelog'ов и баг-репортов:

json
{ "mcpServers": { "brave-search": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-brave-search" ], "env": { "BRAVE_API_KEY": "BSAu_your_brave_search_api_key" } } } }

5. Как Claude Code использует MCP в диалоге

После регистрации сервера специальные команды не требуются. Claude Code анализирует запрос и автономно принимает решение о вызове нужного инструмента.

Пример сценария: работа с GitHub

Запрос пользователя:

"Проверь открытые issues, назначенные на меня в репозитории acme/platform, и выведи самые приоритетные."

Внутренний цикл Claude Code:

  1. Модель понимает, что локальных файлов проекта недостаточно для ответа.
  2. Формирует вызов mcp__github__search_issues с фильтрами repo:acme/platform state:open assignee:@me.
  3. Получает структурированный ответ от GitHub API.
  4. Выдаёт читаемый отчёт:
markdown
Найдено 3 открытых issue, назначенных на вас: 1. **#42 — Fix login redirect loop** (Приоритет: High, Создано: 2 дня назад) 2. **#38 — Add rate limiting to auth API** (Приоритет: Medium, Создано: 5 дней назад) 3. **#35 — Update user profile settings page** (Приоритет: Low, Создано: 1 неделю назад) Хотите подробнее разобрать код для исправления #42?

6. Создание собственного MCP Server на TypeScript

Когда стандартных инструментов недостаточно для внутренней инфраструктуры, собственный сервер можно написать с помощью официального пакета @modelcontextprotocol/sdk.

Шаг 1. Инициализация проекта и зависимости

Создайте отдельную директорию и установите библиотеки:

bash
mkdir my-mcp-server && cd my-mcp-server npm init -y npm install @modelcontextprotocol/sdk zod npm install -D typescript @types/node tsx

Шаг 2. Реализация сервера (server.ts)

Создайте файл server.ts с регистрацией инструмента:

typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { z } from "zod"; // 1. Инициализация сервера const server = new McpServer({ name: "internal-crm-server", version: "1.0.0", }); // 2. Регистрация инструмента с Zod-валидацией аргументов server.tool( "lookup-user", "Найти профиль клиента по адресу электронной почты", { email: z.string().email().describe("Email зарегистрированного пользователя"), }, async ({ email }) => { // Пример интеграции с CRM или внутренней БД const mockUser = { id: "usr_99812", email, name: "Александр Коваленко", plan: "Enterprise", status: "active", createdAt: "2024-03-15T10:00:00Z", }; return { content: [ { type: "text", text: JSON.stringify(mockUser, null, 2), }, ], }; } ); // 3. Запуск через транспорт stdio async function run() { const transport = new StdioServerTransport(); await server.connect(transport); console.error("Internal CRM MCP server started on stdio"); } run().catch((error) => { console.error("Server startup error:", error); process.exit(1); });

Шаг 3. Подключение к настройкам Claude Code

Добавьте сервер в .claude/settings.json:

json
{ "mcpServers": { "crm": { "command": "npx", "args": [ "tsx", "/Users/username/Developer/my-mcp-server/server.ts" ] } } }
Совет

Утилита tsx позволяет исполнять TypeScript-файлы без предварительной компиляции через tsc.

7. Безопасность и изоляция окружения

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

1. Сервер выполняется с вашими системными правами

MCP Server работает от имени текущего пользователя ОС. Ненадежный сервер имеет доступ ко всем файлам и портам вашей учетной записи.

2. Защита секретов и токенов

Не коммитьте боевые ключи в git. Храните чувствительные параметры в ~/.claude/settings.json или передавайте их через .env-файлы, добавленные в .gitignore.

3. Аудит сторонних пакетов перед запуском

Проверяйте репозитории публичных серверов перед запуском:

  • Открытый исходный код и история коммитов.
  • Активность сообщества и число загрузок.
  • Отсутствие скрытых сетевых запросов при инициализации.

4. Разделение уровней конфигурации

text
┌─────────────────────────────────────────────────────────────┐ │ ~/.claude/settings.json │ │ Глобальные инструменты: GitHub, Brave Search, браузер │ └──────────────────────────────┬──────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ .claude/settings.json │ │ Локальные инструменты: Dev PostgreSQL, проектные скрипты │ └─────────────────────────────────────────────────────────────┘
Внимание

Не подключайте серверы с правами записи к производственным базам данных в интерактивных сессиях. Используйте изолированные реплики только для чтения или Docker-контейнеры.

8. Практический воркшоп: пошаговая настройка

Выполните два практических задания для закрепления навыков настройки MCP.

Задание 1. Подключение GitHub MCP Server

  1. Создайте GitHub Personal Access Token с правами repo и read:org.
  2. Добавьте сервер в ~/.claude/settings.json:
json
{ "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_ваш_токен_здесь" } } } }
  1. Запустите новую сессию Claude Code и выполните проверку:
bash
claude

Тестовый промпт:
"Покажи мои 5 последних обновлённых репозиториев на GitHub и их статус."

  • Claude Code успешно вызвал GitHub инструмент без ошибок авторизации.
  • Получен актуальный список репозиториев.

Задание 2. Подключение Filesystem Server для заметок

  1. Добавьте сервер filesystem в .claude/settings.json:
json
{ "mcpServers": { "external-docs": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "/путь/к/папке/с/документами" ] } } }
  1. Отправьте проверочный запрос:

Тестовый промпт:
"Найди в папке external-docs файлы markdown, описывающие архитектуру API, и составь краткий обзор."

  • Claude прочитал файлы за пределами текущего проекта.
  • Корректно обобщил найденную информацию.

9. Быстрая самопроверка знаний

Проверьте, насколько точно вы усвоили архитектуру Model Context Protocol.

Вопрос 1. Что является базовым назначением MCP Server?

  • A. Облачная виртуальная машина для хостинга моделей Claude
  • B. Программа-адаптер, предоставляющая LLM стандартизированный доступ к инструментам и данным
  • C. Библиотека для компрессии векторных эмбеддингов
  • D. Веб-сервер для публикации готового фронтенда
Совет

Правильный ответ: B.
MCP Server выступает в роли адаптера между моделью и сторонними системами, публикуя стандартные Tools, Resources и Prompts.

Вопрос 2. В каком файле хранится конфигурация серверов, предназначенная только для конкретного проекта?

  • A. ~/.claude/settings.json
  • B. package.json
  • C. .claude/settings.json в корне проекта
  • D. CLAUDE.md
Совет

Правильный ответ: C.
Для проектного уровня используется .claude/settings.json, тогда как файл в домашней директории ~/.claude/settings.json отвечает за глобальные инструменты.

Вопрос 3. Как Claude Code определяет, какой инструмент использовать при ответе?

  • A. Пользователь обязан указывать флаг --tool=name перед каждым запросом
  • B. Нужно предварительно вызывать команду /mcp select
  • C. Модель оценивает семантику запроса и схемы инструментов, вызывая подходящий автономно
  • D. Запускаются все инструменты одновременно, а лишние данные отбрасываются
Совет

Правильный ответ: C.
На основе схем и описаний параметров Claude определяет намерение пользователя и передаёт вызовы с валидными аргументами.

10. Итоги и чек-лист архитектуры

Model Context Protocol превращает Claude Code в гибкую платформу разработки. Вместо ручного копирования дампов и схем в чат вы настраиваете надёжные каналы взаимодействия один раз.

Чек-лист готовности среды

  • Уровни настроек: Глобальные инструменты вынесены в ~/.claude/settings.json, проектные — в .claude/settings.json.
  • Безопасность: Токены не попадают в git; базы данных подключены с правами только для чтения.
  • Верификация: Инструменты протестированы целевыми промптами при старте сессии.
  • Расширяемость: Для внутренних задач подготовлен шаблон сервера на TypeScript через @modelcontextprotocol/sdk.
Этот гайд полностью бесплатный. Если он сэкономил вам вечер — вы можете поддержать развитие проекта.
Поддержать автора