MCP GraphQL Server

A Model Context Protocol (MCP) server that enables executing GraphQL queries through Claude Desktop.

Installation

Install the server globally:

npm install -g mcp-graphql-server

Verify the installation:

mcp-graphql --version

Configuration

Claude Desktop Setup

1. Open Claude Desktop's configuration file:

   • macOS: ~/Library/Application Support/Claude Desktop/claude_desktop_config.json
   • Windows: %APPDATA%\Claude Desktop\claude_desktop_config.json

2. Add the server configuration:

{
  "mcpServers": {
    "graphql": {
      "command": "mcp-graphql"
    }
  }
}

3. Restart Claude Desktop after saving the configuration.

4. Verify the server is working:

   • Open Claude Desktop
   • Click the tools icon (hammer)
   • You should see "execute-graphql" in the list of available tools

Troubleshooting

If the tool doesn't appear in Claude Desktop:

1. Verify the installation:

which mcp-graphql  # On macOS/Linux
where mcp-graphql  # On Windows

2. Check the server logs:

   • macOS: ~/Library/Logs/Claude Desktop/mcp*.log
   • Windows: %APPDATA%\Claude Desktop\logs\mcp*.log

3. 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

Environment Variables

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

Usage

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 Usage in Claude

# Example query
{
  "endpoint": "https://api.example.com/graphql",
  "query": "query { viewer { name } }",
  "variables": {
    "id": "123"
  },
  "headers": {
    "Authorization": "Bearer token"
  }
}

Security Features

• Request timeout limits
• Query length validation
• Allowed endpoints configuration
• Input validation
• Error handling with detailed feedback

Development

1. Clone the repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Start in development mode: npm run dev

License

MIT