mcp-graphql-server

1.0.1 • Public • Published

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"
    }
  }
}
  1. Restart Claude Desktop after saving the configuration.

  2. 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
  1. Check the server logs:

    • macOS: ~/Library/Logs/Claude Desktop/mcp*.log
    • Windows: %APPDATA%\Claude Desktop\logs\mcp*.log
  2. 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

Package Sidebar

Install

npm i mcp-graphql-server

Weekly Downloads

5

Version

1.0.1

License

MIT

Unpacked Size

16.4 kB

Total Files

13

Last publish

Collaborators

  • crazyrabbitltc