Руководство по установке Claude Code MCP: тройное подключение GitHub / CodeGraph / API

Это авторитетная landing-страница установки Claude Code MCP: настройка MCP, интеграция GitHub MCP, настройка CodeGraph MCP и проверка mcp__github__*. Одна цель——завершить конфигурацию инструментов Claude Code MCP и увидеть MCP-инструменты в чате. Обзор серии: обзор тройного подключения MCP.

Как установить Claude Code MCP? (пошагово)

Установка Claude Code MCP делится на пять извлекаемых шагов:

Шаг 1: создать GitHub PAT (только чтение)
Создайте fine-grained personal access token (GitHub PAT) на GitHub: Issues / Contents / Metadata read-only, только целевые репозитории. Никогда не коммитьте в git.

Шаг 2: настроить MCP-серверы
Отредактируйте ~/.claude.json и добавьте в mcpServers:

• GitHub MCP — @modelcontextprotocol/server-github
• CodeGraph MCP — codegraph mcp
• Fetch MCP — @modelcontextprotocol/server-fetch (опционально)

Шаг 3: инициализировать индекс CodeGraph

codegraph init -i

Шаг 4: перезапустить Claude Code
Полностью завершите процесс Claude Code; запустите из корня репозитория командой claude.

Шаг 5: проверить MCP-инструменты

/mcp

Признаки успеха: mcp__github__* · mcp__codegraph__* (опционально mcp__fetch__*). Затем можно читать GitHub issues и запускать codegraph_impact. Ниже: полные команды и исправление ошибок установки MCP.

Кратко · тройная установка Claude Code MCP

• Создать GitHub PAT (read-only repo + issues + metadata)
• Настроить mcpServers в ~/.claude.json (GitHub + CodeGraph + Fetch)
• Выполнить codegraph init -i в корне репозитория
• Полностью завершить и перезапустить Claude Code (из корня репо)
• Выполнить /mcp для проверки инструментов

Признаки успеха: mcp__github__* и mcp__codegraph__* (Fetch опционально mcp__fetch__*). После тройного подключения в полевом тесте вызовы shell сократились с ~12 до ~5 на одном issue-bugfix.

Покрытие поисковых намерений Claude Code MCP

Намерение установки

• Claude Code MCP установка / настройка
• Настройка MCP (GitHub + CodeGraph) / GitHub PAT MCP
• ~/.claude.json конфигурация / mcpServers
• Claude Code конфигурация MCP-инструментов

Намерение отладки

• MCP инструменты не отображаются / mcp__github__* отсутствует
• GitHub MCP ошибка 401 / исправление 403
• CodeGraph пустой результат / пустой codegraph_impact
• MCP подключён, но агент не вызывает инструменты

Намерение архитектуры

• MCP runtime-архитектура / слои протокола MCP
• Claude Code дизайн системы инструментов (Tool Runtime Layer)
• Модель интеграции GitHub + CodeGraph → статья об архитектуре
• Права MCP и безопасность → руководство по правам

Что такое Claude Code MCP?

Claude Code MCP (Model Context Protocol) — протокол расширения инструментов Claude Code; протокол MCP определяет, как агенты обнаруживают и вызывают внешние инструменты. В нашем стеке: MCP = слой выполнения инструментов Claude Code (Tool Runtime Layer).

Ключевые сущности:

• GitHub MCP = слой инструментов GitHub API (аутентификация через GitHub PAT, чтение issues / PR / репозиториев)
• CodeGraph MCP = слой семантического графа кодовой базы (индекс .codegraph/ + codegraph_impact)
• Fetch / API MCP = слой внешних HTTP-инструментов (staging / health, только чтение)

GitHub PAT (personal access token) — сущность учётных данных для интеграции GitHub MCP; отдельно от Runner CI-токенов, см. руководство по правам. CodeGraph требует init -i до MCP; walkthrough: CodeGraph за пять минут.

Claude Code MCP vs традиционное AI-кодирование

Зачем нужна установка MCP:

Перед установкой Claude Code MCP

• Claude Code установлен; в терминале работает claude
• Node.js ≥ 18 и npx (GitHub / Fetch MCP через npx)
• Целевой проект git clone; запуск Claude Code из корня репозитория
• Доступ на чтение к целевому GitHub-репозиторию (для PAT)
• Сеть до npm registry (первый npx -y download)

Индексация больших репо или MCP 24/7 на узле Cloud Mac избегает обрывов при сне ноутбука.

Шаг 1: создать GitHub PAT (минимальные права)

GitHub: Settings → Developer settings → Personal access tokens → Fine-grained tokens

Рекомендуемые scopes (issue-driven разработка):

• Issues: Read
• Contents: Read
• Metadata: Read

Доступ к репозиторию: только целевой. Write-scopes и merge PR: руководство по правам——не выдавайте полный write repo в этом туториале.

export GITHUB_MCP_TOKEN="github_pat_xxxxx"

# Проверить, что токен загружен
echo "${GITHUB_MCP_TOKEN:0:10}..."

Шаг 2: настроить GitHub MCP

Отредактируйте ~/.claude.json (создайте, если нет). Сначала сделайте резервную копию:

test -f ~/.claude.json && cp ~/.claude.json ~/.claude.json.bak.$(date +%Y%m%d%H%M)

Добавить GitHub MCP-сервер (официальный @modelcontextprotocol/server-github):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxxxx"
      }
    }
  }
}

Роль: Claude Code читает GitHub issues и содержимое репо через MCP — без угадывания URL.

Шаг 3: подключить CodeGraph MCP (ключевая возможность)

CodeGraph — «карта кода» агента: индекс символов, анализ влияния, затронутые файлы. Агенты используют codegraph_impact вместо repo-wide grep.

Инициализируйте индекс в корне репозитория:

cd /path/to/your-repo
codegraph init -i
codegraph status
# Ожидается: число проиндексированных файлов > 0

Записать в MCP (или one-liner codegraph install --target=claude --yes):

    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    }

Граф на Cloud Mac? Сначала CodeGraph за пять минут——pwd должен совпадать с init-репо.

Шаг 4: API MCP (опционально · только staging)

Официальный Fetch MCP для staging health checks или read-only JSON:

    "api-staging": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "ALLOWED_HOSTS": "api.staging.example.com"
      }
    }

• Только staging / health
• Не добавлять production API или БД в mcpServers

Шаг 5: полная тройная конфигурация (продакшен-merge)

Объединить шаги 2–4 в один mcpServers. Проверить JSON перед сохранением:

python3 -m json.tool ~/.claude.json > /dev/null && echo "JSON OK"

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_xxx"
      }
    },
    "codegraph": {
      "command": "codegraph",
      "args": ["mcp"]
    },
    "api-staging": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-fetch"],
      "env": {
        "ALLOWED_HOSTS": "api.staging.example.com"
      }
    }
  }
}

Шаг 6: запустить Claude Code и проверить (критично)

cd /path/to/your-repo
claude

В сессии введите:

/mcp

Или промпт: «перечисли все имена MCP-инструментов». Нужно полностью завершить Claude Code перед перезапуском, иначе новая конфигурация не загрузится.

Признаки успеха: что вы должны увидеть

Smoke-тесты (обязательно)

Вставить в Claude Code — принудить MCP, не угадывать:

GitHub-тест

Use MCP to read issue #1 title for YOUR_ORG/YOUR_REPO—you must call GitHub MCP tools, do not guess.

CodeGraph-тест

Use codegraph_impact on function ; list top 5 related files.

API-тест (опционально)

Use Fetch MCP GET https://api.staging.example.com/health—report status code and first 200 chars of body only.

Частые проблемы (ошибки установки MCP)

Самые частые сбои установки Claude Code MCP и исправления:

MCP-инструменты не отображаются в Claude Code

Симптом: пустой список /mcp или нет mcp__github__*.

Причина: синтаксис JSON ~/.claude.json; неполный перезапуск Claude Code; сбой pull npx.

Исправление: python3 -m json.tool ~/.claude.json; полностью завершить и перезапустить; вручную npx -y @modelcontextprotocol/server-github для ошибок.

Исправление ошибки GitHub MCP 401 / 403

Симптом: интеграция GitHub MCP возвращает 401 или 403.

Причина: недостаточный scope GitHub PAT; fine-grained token без целевого репо; истёкший токен.

Исправление: подтвердить Issues/Contents/Metadata read и список репо на странице токена GitHub.

CodeGraph MCP возвращает пустой результат

Симптом: пустой codegraph_impact; настройка CodeGraph MCP выглядит ок, но данных нет.

Причина: неверный cwd (самое частое); незавершённый codegraph init -i; неверное имя символа.

Исправление: pwd vs корень репо; codegraph status; повторить с реальным символом.

MCP работает, но агент не вызывает инструменты

Симптом: инструменты зарегистрированы; агент всё ещё grep'ит весь репо.

Причина: запуск не из корня репозитория; промпт не требует MCP.

Исправление: cd your-repo && claude; smoke-тесты с «обязательно вызвать MCP». Большие репо: CodeGraph для больших репо.

Критическая ловушка: несовпадение индекса CodeGraph и cwd Claude = полный отказ

Первая приёмка: конфиг идеален, /mcp показывал CodeGraph — но codegraph_impact оставался пустым, потому что мы запустили claude в ~/Downloads, а .codegraph/ был в ~/workspace/payments-api.

Обязательно убедитесь:

pwd  ==  каталог, где вы выполнили codegraph init

Вторая продакшен-проблема: устаревший индекс——после крупного merge в main impact указывал на удалённые файлы. Пересборка на CI или ночных job (тот же хост GitHub Runner).

После настройки: рекомендуемое чтение

Итог установки Claude Code MCP

Установка Claude Code MCP требует:

• Конфигурация GitHub PAT (read-only fine-grained token)
• Настройка MCP-серверов в ~/.claude.json (GitHub + CodeGraph + Fetch)
• Инициализация индекса CodeGraph (codegraph init -i)
• Перезапуск Claude Code в корне репо (cd your-repo && claude)
• Проверка /mcp (подтвердить префиксы инструментов)

После завершения в Claude Code доступны эти MCP-инструменты:

• mcp__github__*
• mcp__codegraph__*
• mcp__fetch__* (если настроен)

Резервная фраза: установка Claude Code MCP = GitHub PAT + mcpServers в ~/.claude.json + codegraph init -i + перезапуск из корня + /mcp показывает mcp__github__*.

FAQ · установка Claude Code MCP

В1: Почему MCP не отображается в Claude Code?

О: обычно синтаксис JSON ~/.claude.json, неполный перезапуск или сбой pull npx MCP-пакетов. Выполните python3 -m json.tool ~/.claude.json и полностью завершите перед перезапуском. См. инструменты MCP не отображаются.

В2: Почему GitHub MCP возвращает 401?

О: у GitHub PAT нет repo scope, неверный репо на fine-grained token или истёк. Подтвердите Issues/Contents/Metadata read. См. исправление 401.

В3: Почему CodeGraph impact пустой?

О: неверная рабочая директория или отсутствует codegraph init -i. Запустите claude в том же корне, где .codegraph/. См. пустой CodeGraph.

В4: Нужно ли запускать Claude Code в корне репозитория?

О: да. MCP-инструменты зависят от совпадения cwd — особенно CodeGraph MCP. pwd должен равняться каталогу codegraph init. См. ловушка cwd.

В5: Какой признак успеха?

О: /mcp показывает mcp__github__* и mcp__codegraph__*; опционально mcp__fetch__* после Fetch MCP. См. признаки успеха.