A Model Context Protocol (MCP) server that enables executing GraphQL queries through Claude Desktop.
Install the server globally:
npm install -g mcp-graphql-server
Verify the installation:
mcp-graphql --version
-
Open Claude Desktop's configuration file:
- macOS:
~/Library/Application Support/Claude Desktop/claude_desktop_config.json
- Windows:
%APPDATA%\Claude Desktop\claude_desktop_config.json
- macOS:
-
Add the server configuration:
{
"mcpServers": {
"graphql": {
"command": "mcp-graphql"
}
}
}
-
Restart Claude Desktop after saving the configuration.
-
Verify the server is working:
- Open Claude Desktop
- Click the tools icon (hammer)
- You should see "execute-graphql" in the list of available tools
If the tool doesn't appear in Claude Desktop:
- Verify the installation:
which mcp-graphql # On macOS/Linux
where mcp-graphql # On Windows
-
Check the server logs:
- macOS:
~/Library/Logs/Claude Desktop/mcp*.log
- Windows:
%APPDATA%\Claude Desktop\logs\mcp*.log
- macOS:
-
Common issues:
- Ensure Node.js version 16 or higher is installed
- Check that the configuration file path is correct
- Verify the binary is executable (
chmod +x
on Unix systems) - Try using the absolute path to the binary in the configuration
Create a .env
file with the following optional configurations:
# Optional: Set timeout for GraphQL requests (in milliseconds)
GRAPHQL_TIMEOUT=30000
# Optional: Set maximum query length
MAX_QUERY_LENGTH=10000
# Optional: Set allowed endpoints (comma-separated)
ALLOWED_ENDPOINTS=https://api.example.com/graphql,https://api2.example.com/graphql
The server provides a tool for executing GraphQL queries:
- Tool name:
execute-graphql
- Parameters:
-
endpoint
(required): GraphQL endpoint URL -
query
(required): GraphQL query string -
variables
(optional): Query variables -
headers
(optional): Custom headers
-
# Example query
{
"endpoint": "https://api.example.com/graphql",
"query": "query { viewer { name } }",
"variables": {
"id": "123"
},
"headers": {
"Authorization": "Bearer token"
}
}
- Request timeout limits
- Query length validation
- Allowed endpoints configuration
- Input validation
- Error handling with detailed feedback
- Clone the repository
- Install dependencies:
npm install
- Build the project:
npm run build
- Start in development mode:
npm run dev
MIT