GraphQL MCP 서버

Claude AI를 통해 모든 GraphQL API에 원활하게 액세스할 수 있는 강력한 형식의 TypeScript 모델 컨텍스트 프로토콜(MCP) 서버입니다.

특징

강력한 형식 : 향상된 코드 품질과 유형 안전성을 위해 TypeScript로 구축됨
동적 GraphQL 통합 : 자동 도구 생성을 통해 모든 GraphQL API에 연결
스키마 내성 : 모든 GraphQL 작업을 도구로 자동으로 검색하고 노출합니다.
전체 변형 지원 : 적절한 처리를 통해 GraphQL 변형에 대한 일류 지원
쿼리 및 변형 허용 목록 : GraphQL 작업이 노출되는 것을 제어하기 위한 선택적 허용 목록
풍부한 유형 지원 : 복잡한 GraphQL 유형, 입력 객체 및 변수를 적절하게 처리합니다.
MCP 표준 준수 : 원활한 Claude 통합을 위해 모델 컨텍스트 프로토콜 형식을 따릅니다.
스마트 쿼리 생성 : 적절한 필드 선택을 통해 효율적인 GraphQL 쿼리를 구축합니다.
인증 지원 : 간단한 API 키 인증

저장소 구조

지엑스피1

필수 조건

Node.js 18 이상
TypeScript 5.x 이상
MCP 지원이 포함된 Claude Desktop
GraphQL API 엔드포인트(지정하지 않으면 Countries API로 기본 설정됨)

설치

옵션 1: npm에서

# Install globally
npm install -g graphql-mcp

# Run the server
graphql-mcp-server

옵션 2: 저장소 복제

# Clone the repository
git clone https://github.com/ctkadvisors/graphql-mcp.git
cd graphql-mcp

# Install dependencies
npm install

# Run the server
npm start

빠른 시작

1. 환경 변수 설정

샘플 env 파일을 복사하고 GraphQL API 세부정보로 업데이트하세요.

cp .env.sample .env.development

GraphQL API 엔드포인트와 선택적 API 키로 .env.development 편집합니다.

2. 빌드 및 실행

먼저 TypeScript 코드를 컴파일합니다.

npm install
npm run build

그런 다음 서버를 실행합니다.

node dist/graphql-mcp-server.js

또는 한 단계로 컴파일하고 실행하는 제공된 스크립트를 사용하세요.

./run-graphql-mcp.sh

3. Claude 데스크톱 통합

Claude Desktop 구성에 이 서버를 추가하세요:

샘플 구성을 템플릿으로 사용하세요.
cp claude_desktop_sample_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
구성을 편집하고 설치를 가리키도록 경로를 업데이트하세요.
{ "mcpServers": { "graphql": { "command": "node", "args": ["/absolute/path/to/dist/graphql-mcp-server.js"], "env": { "GRAPHQL_API_ENDPOINT": "https://your-graphql-api.com/graphql", "GRAPHQL_API_KEY": "your-api-key-if-needed", "WHITELISTED_QUERIES": "[\"countries\",\"continent\",\"languages\"]" } } } }
서버에 연결하려면 Claude Desktop을 다시 시작하세요.

이제 Claude Desktop에서 GraphQL 작업을 사용할 수 있는 도구로 볼 수 있습니다!

화이트리스트 작업

보안이나 성능상의 이유로 Claude에 노출되는 GraphQL 작업(쿼리 및 뮤테이션)을 제한할 수 있습니다. 액세스를 제어하는 두 가지 방법이 있습니다.

변형 활성화/비활성화 : 기본적으로 모든 변형은 보안을 위해 비활성화되어 있습니다. 변형을 활성화하려면:

"env": {
  "GRAPHQL_API_ENDPOINT": "https://example-graphql-api.com/graphql",
  "ENABLE_MUTATIONS": "true"
}

작업 허용 목록 : 어떤 특정 작업을 허용할지 지정할 수 있습니다.

"env": {
  "GRAPHQL_API_ENDPOINT": "https://example-graphql-api.com/graphql",
  "ENABLE_MUTATIONS": "true",
  "WHITELISTED_QUERIES": "[\"countries\",\"continent\",\"languages\"]",
  "WHITELISTED_MUTATIONS": "[\"createUser\",\"updateProfile\"]"
}

허용 목록은 두 가지 형식으로 지정할 수 있습니다.

JSON 배열 문자열(위에 표시): "[\"query1\",\"query2\"]"
쉼표로 구분된 목록: "query1,query2,query3"

중요 : 허용 목록 값은 실제 JSON 배열 객체가 아닌 문자열이어야 합니다. 환경 변수는 항상 문자열로 전달되므로 위에 표시된 것처럼 JSON 문자열의 따옴표를 올바르게 이스케이프 처리해야 합니다.

Claude Desktop 구성의 올바른 형식 예 :

"graphql-api": {
  "command": "node",
  "args": [
    "/Users/username/Projects/graphql-mcp/dist/graphql-mcp-server.js"
  ],
  "env": {
    "GRAPHQL_API_ENDPOINT": "https://example-graphql-api.com/graphql",
    "NODE_ENV": "development",
    "DEBUG": "true",
    "ENABLE_MUTATIONS": "true",
    "WHITELISTED_QUERIES": "[\"getUser\",\"getProducts\",\"getOrders\"]",
    "WHITELISTED_MUTATIONS": "[\"createOrder\",\"updateProfile\"]"
  }
}

피해야 할 일반적인 실수 :

// INCORRECT - Will not work!
"WHITELISTED_QUERIES": ["getUser", "getProducts"],
"WHITELISTED_MUTATIONS": ["createOrder", "updateProfile"]

// CORRECT
"WHITELISTED_QUERIES": "[\"getUser\",\"getProducts\"]",
"WHITELISTED_MUTATIONS": "[\"createOrder\",\"updateProfile\"]"

특정 작업 유형에 대한 허용 목록이 제공되지 않으면 GraphQL 스키마의 해당 유형의 모든 작업을 사용할 수 있습니다.

사용 예

데이터 쿼리

Claude Desktop에 연결되면 다음과 같은 명령을 사용할 수 있습니다.

View result from countries from graphql (local){}

또는 매개변수를 사용하여:

View result from country from graphql (local){
  "code": "US"
}

돌연변이 사용

돌연변이의 경우 도구에는 mutation_ 가 붙어 쿼리와 구별됩니다.

View result from mutation_createUser from graphql (local){
  "name": "John Doe",
  "email": "john.doe@example.com"
}

또는 더 복잡한 돌연변이:

View result from mutation_updateProduct from graphql (local){
  "id": "prod-123",
  "input": {
    "name": "Updated Product Name",
    "price": 29.99,
    "description": "This is an updated product description"
  }
}

변형은 쿼리와 동일한 패턴을 따르지만 GraphQL API에서 데이터를 수정할 수 있습니다.

선적 서류 비치

자세한 내용은 다음을 참조하세요.

개발

서버를 변경하려면:

src/graphql-mcp-server.ts 에서 TypeScript 소스를 수정하세요.
TypeScript 코드를 컴파일합니다: npm run build
컴파일된 서버를 실행합니다: node dist/graphql-mcp-server.js

npm에 게시하기

이 패키지를 npm에 게시하려면:

# Make sure you're logged in to npm
npm login

# Build the project
npm run build

# Publish to npm
npm publish

패키지에는 dist 디렉토리에 미리 빌드된 JavaScript 파일이 포함되어 있어 추가 빌드 단계 없이 바로 사용할 수 있습니다.

특허

이 프로젝트는 Business Source License 1.1(BSL 1.1)에 따라 라이선스가 부여되었으며, 이를 통해 다음이 허용됩니다.

비상업적 사용 : 이 소프트웨어는 비상업적 목적으로 사용할 수 있습니다.
내부 비즈니스 사용 : 귀하는 이 소프트웨어를 호스팅 또는 관리 서비스로 제3자에게 제공하지 않는 내부 비즈니스 운영에 사용할 수 있습니다.
오픈소스 전환 : 2029년 3월 14일부터 코드가 자동으로 MIT 라이선스로 전환됩니다.

이 소프트웨어를 타인에게 서비스로 제공하는 등 상업적 용도로 사용하려면 CTK Advisors의 상업적 라이선스가 필요합니다. 자세한 내용은 당사에 문의하시거나 전체 라이선스 파일을 참조하십시오.

BSL 라이선스는 오픈 소스의 가용성과 지속 가능한 상업적 개발 간의 균형을 맞추도록 설계되었으며, 비상업적 목적으로는 모든 사람에게 무료 액세스를 제공하는 동시에 소프트웨어를 장기적으로 지원하고 개선할 수 있는 당사의 능력을 보호합니다.

GraphQL MCP Server

Integrations