Skip to main content
Glama
deenesjakoruzh
murilojrpereira

mcp-graphql-bridge

by murilojrpereira
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

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 탐색 도구를 등록합니다

요구 사항

  • 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)

Install Server
A
license - permissive license
A
quality
C
maintenance

How are these scores calculated?

Resources

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/murilojrpereira/mcp-graphql-bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server