mcp-graphql-bridge

Универсальный MCP-сервер (Model Context Protocol), который связывает любой GraphQL API с Claude Code. Он анализирует вашу схему GraphQL и предоставляет каждый запрос (query) и мутацию (mutation) в виде отдельного инструмента, позволяя Claude взаимодействовать с вашим API напрямую.

Как это работает

При запуске сервер:

1. Ищет файл schema-introspection.json в рабочей директории (быстро, без сетевого вызова)

2. Если файл не найден, выполняет интроспекцию в реальном времени по адресу GRAPHQL_INTROSPECTION_URL

3. Регистрирует по одному инструменту на каждый запрос (query__<name>) и на каждую мутацию (mutation__<name>)

4. Всегда регистрирует универсальный инструмент execute_graphql для резервного выполнения и инструмент get_type_details для исследования схемы

Требования

• Node.js >= 18

Настройка

Шаг 1: Установка

Вариант A: Установка из npm (рекомендуется)

npm install -g mcp-graphql-bridge

Вариант B: Клонирование и сборка из исходного кода

git clone https://github.com/murilopereira/mcp-graphql-bridge.git
cd mcp-graphql-bridge
npm install
npm run build

Шаг 2: Настройка переменных окружения

Вы можете задать их в файле .env в корне проекта:

GRAPHQL_API_URL=https://your-api.example.com/graphql
GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql
GRAPHQL_TOKEN=your-bearer-token

Или передать их напрямую через команду claude mcp add (см. ниже).

Шаг 3: (Опционально) Предварительная генерация снимка схемы

По умолчанию сервер выполняет интроспекцию схемы при запуске — файл не требуется. Используйте этот шаг только в том случае, если в вашем API отключена интроспекция в продакшене или если вы хотите ускорить время запуска:

curl -s -X POST https://your-api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-bearer-token" \
  -d '{"query":"{ __schema { queryType { fields { name description args { name description defaultValue type { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } type { kind name ofType { kind name ofType { kind name } } } } } mutationType { fields { name description args { name description defaultValue type { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } type { kind name ofType { kind name ofType { kind name } } } } } } }"}' \
  > schema-introspection.json

Добавление в Claude Code

Вариант A: Область пользователя (только для вас)

Если установлено из npm:

claude mcp add --transport stdio \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- mcp-graphql-bridge

Если клонировано из исходного кода:

claude mcp add --transport stdio \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- node /absolute/path/to/mcp-graphql-bridge/dist/index.js

Важно: Убедитесь, что используете mcp-graphql-bridge/dist/index.js (скомпилированный результат), а не mcp-graphql-bridge/index.js. Исходный код на TypeScript должен быть сначала собран с помощью npm run build, а точка входа находится в папке dist/.

Вариант B: Область проекта (общий доступ для команды через .mcp.json)

claude mcp add --transport stdio --scope project \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- mcp-graphql-bridge

Примечание: Используйте абсолютные пути. Все флаги --env и --transport должны идти перед именем сервера.

Проверка соединения

claude mcp list

Затем в сессии Claude Code выполните /mcp, чтобы увидеть доступные серверы и инструменты.

Доступные инструменты

Все инструменты для операций принимают специальный аргумент __fields, в котором можно указать пользовательский набор полей GraphQL (например, { id name status }). Если аргумент опущен, возвращаются только скалярные поля.

Docker

Сборка образа

docker build -t mcp-graphql-bridge .

Добавление в Claude Code через Docker

claude mcp add --transport stdio \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- docker run -i --rm \
  -e GRAPHQL_API_URL -e GRAPHQL_INTROSPECTION_URL -e GRAPHQL_TOKEN \
  mcp-graphql-bridge

Примечание: Флаг -i (без -t) обязателен — он оставляет stdin открытым для протокола MCP stdio.

Разработка

npm run dev   # watch mode: rebuilds and restarts on file changes
npm run build # one-off TypeScript compile
npm start     # run the compiled server

Устранение неполадок

Ошибка: Cannot find module '.../index.js'

Если вы видите ошибку вида:

Error: Cannot find module '/path/to/mcp-graphql-bridge/index.js'

Вы указываете не на тот файл. Исходный код на TypeScript должен быть сначала скомпилирован, а точка входа находится в папке dist/:

Правильный путь: /path/to/mcp-graphql-bridge/dist/index.js Неправильный путь: /path/to/mcp-graphql-bridge/index.js

Решение:

1. Убедитесь, что вы выполнили npm run build (создается папка dist/)

2. Обновите конфигурацию MCP, чтобы использовать полный путь, заканчивающийся на /dist/index.js

Ошибка интроспекции схемы

Если сервер запускается, но показывает "Schema introspection failed", возможно, в вашем GraphQL API отключена интроспекция в продакшене. Используйте команду curl из шага 3 раздела "Настройка", чтобы предварительно сгенерировать файл schema-introspection.json.

Инструменты не появляются в Claude Code

1. Выполните claude mcp list, чтобы убедиться, что сервер зарегистрирован

2. Выполните /mcp в сессии Claude Code, чтобы увидеть доступные инструменты

3. Проверьте, что заданы все необходимые переменные окружения (GRAPHQL_API_URL, GRAPHQL_INTROSPECTION_URL, GRAPHQL_TOKEN)