关键词

graphqlapi集成工具服务器typescript数据访问

使用说明

项目简介

GraphQL MCP Server 是一个实现了 Model Context Protocol (MCP) 的服务器，它作为一个桥梁，可以将任何 GraphQL API 转化为 LLM (如 Claude) 可以理解和调用的工具。通过该服务器，用户可以使用自然语言指令，让 LLM 客户端直接查询和操作 GraphQL API 中的数据，极大地扩展了 LLM 的数据访问能力。

主要功能点

  • 动态 GraphQL 集成: 自动连接并发现任何 GraphQL API，无需手动配置工具。
  • Schema 自省: 自动获取 GraphQL Schema，并将其中的 Query 和 Mutation 转化为工具。
  • Mutation 支持: 全面支持 GraphQL Mutation 操作，允许 LLM 修改数据。
  • 操作白名单: 可选配置 Query 和 Mutation 白名单，控制暴露给 LLM 的操作范围，保障安全和性能。
  • 丰富的类型支持: 支持复杂的 GraphQL 类型、输入对象和变量。
  • MCP 标准兼容: 完全遵循 Model Context Protocol 标准，无缝集成 Claude 等 MCP 客户端。
  • 智能查询生成: 自动构建高效的 GraphQL 查询，优化数据获取。
  • 认证支持: 支持 API Key 认证，保护 GraphQL API 的访问安全。

安装步骤

方式一：通过 npm 全局安装

npm install -g graphql-mcp

方式二：克隆仓库

git clone https://github.com/ctkadvisors/graphql-mcp.git
cd graphql-mcp
npm install

服务器配置

要将 GraphQL MCP Server 集成到 MCP 客户端（例如 Claude Desktop），您需要在客户端的 MCP 服务器配置中添加以下 JSON 配置。请根据您的实际安装路径调整 'args' 中的路径。

{
  "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": "[\"query1\",\"query2\"]",
        "ENABLE_MUTATIONS": "true"
      }
    }
  }
}

配置参数说明:

  • 'server name': 'graphql' (服务器名称，可自定义)
  • 'command': 'node' (运行命令，通常为 node)
  • 'args': '["/absolute/path/to/dist/graphql-mcp-server.js"]' (启动服务器的脚本路径，请替换为 graphql-mcp-server.js 的实际绝对路径)
  • 'env': 环境变量配置，包含：
    • 'GRAPHQL_API_ENDPOINT': GraphQL API 的终端地址 (例如: 'https://countries.trevorblades.com/graphql')
    • 'GRAPHQL_API_KEY': 访问 GraphQL API 的 API Key (如果需要)
    • 'WHITELISTED_QUERIES': 允许暴露的 GraphQL Query 操作白名单，JSON 数组字符串格式 (例如: '["countries", "continent"]')，留空则允许所有 Query。
    • 'ENABLE_MUTATIONS': 是否启用 GraphQL Mutation 操作，'true' 为启用，'false' 为禁用 (默认为 'false'，出于安全考虑)。

启动服务器:

方式一：全局安装

graphql-mcp-server

方式二：克隆仓库

npm run build
node dist/graphql-mcp-server.js

或者使用脚本：

./run-graphql-mcp.sh

基本使用方法

成功配置并启动 GraphQL MCP Server 后，您可以在 MCP 客户端中使用自然语言指令调用 GraphQL API 的能力。

查询数据 (Queries):

使用 '工具名称 (server name)' 的格式来调用 GraphQL 查询工具。工具名称通常与 GraphQL Schema 中的 Query Field 名称一致。

例如，查询 'countries' 数据 (假设 GraphQL Schema 中有 'countries' Query):

View result from countries from graphql (local){}

如果 Query 需要参数，可以在 '{}' 中以 JSON 格式提供参数。例如，查询 'country' 数据，并指定 'code' 参数:

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

操作数据 (Mutations):

Mutation 工具的名称通常以 'mutation_' 前缀开头，以区分于 Query 工具。

例如，调用 'createUser' Mutation (假设 GraphQL Schema 中有 'createUser' Mutation):

View result from mutation_createUser from graphql (local){
  "name": "John Doe",
  "email": "[email protected]"
}

Mutation 的参数也以 JSON 格式在 '{}' 中提供。

请参考您的 GraphQL API 文档，了解可用的 Query 和 Mutation 以及它们需要的参数，然后在 MCP 客户端中使用相应的工具进行调用。

信息

分类

网页与API

访问项目