Skip to main content
Glama
mcp-graphql-bridge

mcp-graphql-bridge

mcp-graphql-bridge

npm version CI License: MIT Node.js >= 18

모든 GraphQL API를 Claude Code에 연결하는 범용 MCP(Model Context Protocol) 서버입니다. GraphQL 스키마를 인트로스펙션(introspection)하여 각 쿼리와 뮤테이션을 개별 도구로 노출함으로써, Claude가 API와 직접 상호작용할 수 있도록 합니다.

작동 방식

서버가 시작되면 다음을 수행합니다:

  1. 작업 디렉토리에서 schema-introspection.json 파일을 찾습니다 (빠르고 네트워크 호출 없음)

  2. 파일을 찾을 수 없으면 GRAPHQL_INTROSPECTION_URL에 대해 실시간 인트로스펙션을 실행합니다

  3. 쿼리당 하나의 도구(query__<name>)와 뮤테이션당 하나의 도구(mutation__<name>)를 등록합니다

  4. 항상 범용 execute_graphql 폴백 도구와 get_type_details 탐색 도구를 등록합니다

Related MCP server: GraphQL MCP Server

요구 사항

  • 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단계: 환경 변수 설정

변수

필수 여부

설명

GRAPHQL_API_URL

예

쿼리 및 뮤테이션에 사용되는 엔드포인트

GRAPHQL_INTROSPECTION_URL

예

스키마 인트로스펙션에 사용되는 엔드포인트 (위와 동일할 수 있음)

GRAPHQL_TOKEN

예

인증을 위한 Bearer 토큰

프로젝트 루트의 .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/index.js가 아닌 mcp-graphql-bridge/dist/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를 실행하여 사용 가능한 서버와 도구를 확인하세요.

사용 가능한 도구

도구

설명

query__<name>

GraphQL 쿼리 필드당 하나의 도구

mutation__<name>

GraphQL 뮤테이션 필드당 하나의 도구

execute_graphql

범용 폴백 — 모든 쿼리 또는 뮤테이션 실행

get_type_details

특정 GraphQL 타입의 필드 탐색

모든 작업별 도구는 사용자 지정 GraphQL 선택 세트(예: { id name status })를 제공할 수 있는 특수 __fields 인수를 허용합니다. 생략하면 스칼라 필드만 반환됩니다.

Docker

이미지 빌드

docker build -t mcp-graphql-bridge .

Docker를 통해 Claude Code에 추가

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 제외)가 필요합니다. 이는 MCP stdio 프로토콜을 위해 stdin을 열어둡니다.

개발

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의 프로덕션 환경에서 인트로스펙션이 비활성화되었을 수 있습니다. 설정 3단계의 curl 명령을 사용하여 schema-introspection.json 파일을 사전 생성하세요.

Claude Code에 도구가 나타나지 않음

  1. claude mcp list를 실행하여 서버가 등록되었는지 확인하세요

  2. Claude Code 세션에서 /mcp를 실행하여 사용 가능한 도구를 확인하세요

  3. 필요한 모든 환경 변수가 설정되었는지 확인하세요 (GRAPHQL_API_URL, GRAPHQL_INTROSPECTION_URL, GRAPHQL_TOKEN)

Available Tools

2 tools
execute_graphqlA

Execute any GraphQL query or mutation against the API. Use this when no specific tool exists for your operation.

Inputs: query (required), variables, bearer_token, custom_headers.

get_type_detailsB

Get fields of a specific GraphQL type to know what to put in __fields

Inputs: typeName (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools serve clearly distinct purposes: executing GraphQL operations vs. retrieving type metadata. No overlap in functionality.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern using snake_case (execute_graphql, get_type_details), making the intent clear and predictable.

    Tool Count4/5

    For a GraphQL bridge, two tools is minimal but still covers the essential operations of executing queries and exploring types. Slightly under-scoped but reasonable.

    Completeness4/5

    The tool surface covers core GraphQL operations (any query/mutation) and type introspection. Minor gaps exist (e.g., no dedicated tool for listing mutations), but the generic execute tool and type details suffice for agents familiar with GraphQL.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A MCP server that exposes GraphQL schema information to LLMs like Claude. This server allows an LLM to explore and understand large GraphQL schemas through a set of specialized tools, without needing to load the whole schema into the context
      46
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables LLMs to interact with GraphQL APIs by providing schema introspection and query execution capabilities.
      3
      MIT