# 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 интерпретирует полученные данные и формирует итоговый структурированный ответ. > [!NOTE] > Взаимодействие прозрачно для разработчика: не нужно вручную помнить параметры методов или синтаксис API. Claude выбирает подходящий инструмент автономно на основе контекста. --- ## 3. Как подключить MCP Server к Claude Code Серверы подключаются через JSON-конфигурацию в секции `mcpServers`. Claude Code поддерживает два уровня конфигурации: 1. **Конфигурация проекта (`.claude/settings.json`)** — действует исключительно в рамках текущей папки и может безопасно храниться в репозитории для всей команды. 2. **Глобальная конфигурация (`~/.claude/settings.json`)** — доступна для всех проектов текущего пользователя в операционной системе. :::tabs === Проект (.claude/settings.json) ```json { "mcpServers": { "filesystem": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-filesystem", "./docs" ] } } } ``` === Глобально (~/.claude/settings.json) ```json { "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@anthropic-ai/mcp-github" ], "env": { "GITHUB_TOKEN": "ghp_your_token_here" } } } } ``` ::: ### Параметры конфигурации Каждая запись сервера в `mcpServers` состоит из трёх ключевых полей: | Параметр | Тип | Обязательный | Описание и назначение | Примеры значений | | :--- | :--- | :--- | :--- | :--- | | `command` | `string` | Да | Исполняемая команда запуска процесса сервера | `"npx"`, `"node"`, `"uvx"`, `"docker"` | | `args` | `string[]` | Да | Массив аргументов запуска (имя пакета, пути, флаги) | `["-y", "@anthropic-ai/mcp-filesystem", "/path"]` | | `env` | `object` | Нет | Переменные окружения для авторизации и API-ключей | `{"GITHUB_TOKEN": "ghp_...", "DEBUG": "1"}` | > [!TIP] > Если вы используете MCP-серверы на Python, вместо `npx` можно применять `uvx`: `"command": "uvx", "args": ["mcp-server-git"]`. --- ## 4. Каталог готовых MCP Servers Официальные и проверенные сообществом серверы закрывают большинство типичных задач разработчика: | Сервер | Официальный пакет | Доступ / Аутентификация | Основные возможности | | :--- | :--- | :--- | :--- | | **Filesystem** | `@anthropic-ai/mcp-filesystem` | Пути к разрешённым локальным папкам | Чтение, запись и поиск в каталогах вне корня проекта | | **GitHub** | `@anthropic-ai/mcp-github` | Personal Access Token (`GITHUB_TOKEN`) | Поиск по репозиториям, анализ issues, ревью PR | | **PostgreSQL** | `@anthropic-ai/mcp-postgres` | Строка подключения (`connectionString`) | Чтение схемы, просмотр таблиц, выполнение SQL | | **Brave Search** | `@anthropic-ai/mcp-brave-search` | API-ключ поиска (`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" ] } } } ``` > [!TIP] > Утилита `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, проектные скрипты │ └─────────────────────────────────────────────────────────────┘ ``` > [!WARNING] > Не подключайте серверы с правами записи к производственным базам данных в интерактивных сессиях. Используйте изолированные реплики только для чтения или 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_ваш_токен_здесь" } } } } ``` 3. Запустите новую сессию 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", "/путь/к/папке/с/документами" ] } } } ``` 2. Отправьте проверочный запрос: > **Тестовый промпт:** > "Найди в папке external-docs файлы markdown, описывающие архитектуру API, и составь краткий обзор." - [ ] Claude прочитал файлы за пределами текущего проекта. - [ ] Корректно обобщил найденную информацию. --- ## 9. Быстрая самопроверка знаний Проверьте, насколько точно вы усвоили архитектуру Model Context Protocol. ### Вопрос 1. Что является базовым назначением MCP Server? - **A.** Облачная виртуальная машина для хостинга моделей Claude - **B.** Программа-адаптер, предоставляющая LLM стандартизированный доступ к инструментам и данным - **C.** Библиотека для компрессии векторных эмбеддингов - **D.** Веб-сервер для публикации готового фронтенда > [!TIP] > **Правильный ответ: B.** > MCP Server выступает в роли адаптера между моделью и сторонними системами, публикуя стандартные Tools, Resources и Prompts. --- ### Вопрос 2. В каком файле хранится конфигурация серверов, предназначенная только для конкретного проекта? - **A.** `~/.claude/settings.json` - **B.** `package.json` - **C.** `.claude/settings.json` в корне проекта - **D.** `CLAUDE.md` > [!TIP] > **Правильный ответ: C.** > Для проектного уровня используется `.claude/settings.json`, тогда как файл в домашней директории `~/.claude/settings.json` отвечает за глобальные инструменты. --- ### Вопрос 3. Как Claude Code определяет, какой инструмент использовать при ответе? - **A.** Пользователь обязан указывать флаг `--tool=name` перед каждым запросом - **B.** Нужно предварительно вызывать команду `/mcp select` - **C.** Модель оценивает семантику запроса и схемы инструментов, вызывая подходящий автономно - **D.** Запускаются все инструменты одновременно, а лишние данные отбрасываются > [!TIP] > **Правильный ответ: C.** > На основе схем и описаний параметров Claude определяет намерение пользователя и передаёт вызовы с валидными аргументами. --- ## 10. Итоги и чек-лист архитектуры Model Context Protocol превращает Claude Code в гибкую платформу разработки. Вместо ручного копирования дампов и схем в чат вы настраиваете надёжные каналы взаимодействия один раз. ### Чек-лист готовности среды - [x] **Уровни настроек:** Глобальные инструменты вынесены в `~/.claude/settings.json`, проектные — в `.claude/settings.json`. - [x] **Безопасность:** Токены не попадают в git; базы данных подключены с правами только для чтения. - [x] **Верификация:** Инструменты протестированы целевыми промптами при старте сессии. - [x] **Расширяемость:** Для внутренних задач подготовлен шаблон сервера на TypeScript через `@modelcontextprotocol/sdk`.