A Model Context Protocol (MCP) server that provides comprehensive GraphQL introspection capabilities with filtering and detailed analysis features.

• Complete Schema Introspection: Get full GraphQL schema with SDL and structured data
• Smart Filtering: Filter queries, mutations, and types with search patterns
• Detailed Analysis: Get comprehensive information about specific types and fields
• Query Execution: Execute read-only GraphQL queries against any endpoint
• Mutation Support: Execute GraphQL mutations with explicit opt-in via ALLOW_MUTATIONS flag
• Safety Controls: 3-layer protection with tool listing, execution guards, and GraphQL AST validation

By default, only read-only operations are available:

• All 6 introspection tools (schema, queries, mutations, types, type details, field details)
• execute_query — executes GraphQL queries only

To enable mutation execution, set the ALLOW_MUTATIONS environment variable:

ALLOW_MUTATIONS=true npx graphql-inspector-mcp

Or in your MCP config:

{
  "mcpServers": {
    "graphql-introspection": {
      "command": "npx",
      "args": ["-y", "graphql-inspector-mcp"],
      "env": {
        "ALLOW_MUTATIONS": "true"
      }
    }
  }
}

When enabled, the execute_mutation tool becomes available.

Three layers of protection prevent unauthorized mutations:

1. Tool Listing: execute_mutation is hidden from tool discovery when ALLOW_MUTATIONS is not set
2. Execution Guard: Even if called directly, execute_mutation rejects when not in dangerous mode
3. AST Validation: GraphQL documents are parsed and validated — operation type is verified at the AST level, not string matching

• MCP Annotations: All tools annotated with readOnlyHint for MCP-aware clients
• Authentication Support: Basic Auth and Bearer token authentication
• Caching: In-memory caching with 5-minute expiration for better performance
• AI-Friendly Output: Structured JSON responses optimized for AI agents

npm install
npm run build

You can run the tool directly via npx:

npx graphql-inspector-mcp

This will start the MCP server and expose GraphQL introspection tools.

The following arguments can be provided via JSON config, environment variables, or MCP tool requests. They are not traditional CLI flags, but are passed as options to the server or tools.

npx graphql-inspector-mcp

With config file (mcp.config.json):

{
  "mcpServers": {
    "graphql-introspection": {
      "command": "npx",
      "args": [
        "-y",
        "kokorolx/graphql-inspector-mcp"
      ],
      "options": {
        "endpoint": "http://localhost:5555/graphql"
      }
    }
  }
}

Or via environment variables:

export GRAPHQL_DEFAULT_ENDPOINT="http://localhost:4000/graphql"
export CACHE_DURATION_MS="600000"

Or via MCP tool request JSON:

{
  "endpoint": "http://localhost:5555/graphql",
  "search": "user",
  "detailed": true
}

The MCP config file allows you to customize server settings and tool behavior. By default, the config file should be named mcp.config.json and placed in your project root.

Example mcp.config.json:

{
  "mcpServers": {
    "graphql-introspection": {
      "command": "npx",
      "args": [
        "-y",
        "kokorolx/graphql-inspector-mcp"
      ],
      "options": {
        "endpoint": "http://localhost:5550/graphql"
      }
    }
  }
}

• Location: Project root (e.g., ./mcp.config.json)
• Format: Standard JSON
• Usage: The MCP client will automatically detect and use this configuration when starting the server.

Get complete GraphQL schema introspection with SDL and structured data.

{
  "endpoint": "http://localhost:5555/graphql",
  "username": "optional_username",
  "password": "optional_password",
  "bearer_token": "optional_bearer_token"
}

Filter and list available GraphQL queries with optional search.

{
  "endpoint": "http://localhost:5555/graphql",
  "search": "user",
  "detailed": true
}

Filter and list available GraphQL mutations with optional search.

{
  "endpoint": "http://localhost:5555/graphql",
  "search": "create",
  "detailed": false
}

Filter and list available GraphQL types by kind and search pattern.

{
  "endpoint": "http://localhost:5555/graphql",
  "search": "User",
  "kind": "OBJECT",
  "detailed": true
}

Supported type kinds:

• OBJECT - Object types
• SCALAR - Scalar types
• ENUM - Enumeration types
• INTERFACE - Interface types
• UNION - Union types
• INPUT_OBJECT - Input object types

Get comprehensive information about a specific GraphQL type.

{
  "type_name": "User",
  "endpoint": "http://localhost:5555/graphql"
}

Get detailed information about a specific query or mutation field.

{
  "field_name": "getUser",
  "operation_type": "query",
  "endpoint": "http://localhost:5555/graphql"
}

Execute a read-only GraphQL query against the endpoint.

{
  "query": "query { users { id name email } }",
  "variables": {},
  "endpoint": "http://localhost:5555/graphql"
}

Execute a GraphQL mutation (requires ALLOW_MUTATIONS=true).

{
  "query": "mutation { createUser(name: \"John\") { id name } }",
  "variables": {},
  "endpoint": "http://localhost:5555/graphql"
}

The server supports multiple authentication methods:

{
  "endpoint": "https://api.example.com/graphql",
  "username": "your_username",
  "password": "your_password"
}

{
  "endpoint": "https://api.example.com/graphql",
  "bearer_token": "your_jwt_token"
}

All responses are structured JSON optimized for AI processing:

{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "data": {
    // ... relevant data
  }
}

{
  "success": false,
  "error": "Error description",
  "endpoint": "http://localhost:5555/graphql"
}

{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "search_term": "user",
  "queries": [
    {
      "name": "getUser",
      "description": "Fetch a user by ID",
      "deprecated": false,
      "deprecation_reason": null
    },
    {
      "name": "searchUsers",
      "description": "Search users by criteria",
      "deprecated": false,
      "deprecation_reason": null
    }
  ],
  "total": 2
}

{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "queries": [
    {
      "name": "getUser",
      "description": "Fetch a user by ID",
      "deprecated": false,
      "deprecation_reason": null,
      "arguments": [
        {
          "name": "id",
          "description": "User ID",
          "type": {
            "kind": "NON_NULL",
            "of_type": {
              "kind": "SCALAR",
              "name": "ID"
            },
            "is_required": true
          },
          "default_value": null
        }
      ],
      "return_type": {
        "kind": "OBJECT",
        "name": "User",
        "description": "A user in the system"
      }
    }
  ],
  "total": 1
}

{
  "success": true,
  "endpoint": "http://localhost:5555/graphql",
  "type": {
    "name": "User",
    "kind": "OBJECT",
    "description": "A user in the system",
    "fields": [
      {
        "name": "id",
        "description": "Unique identifier",
        "type": {
          "kind": "NON_NULL",
          "of_type": {
            "kind": "SCALAR",
            "name": "ID"
          },
          "is_required": true
        },
        "deprecated": false,
        "deprecation_reason": null
      },
      {
        "name": "email",
        "description": "User email address",
        "type": {
          "kind": "SCALAR",
          "name": "String"
        },
        "deprecated": false,
        "deprecation_reason": null
      }
    ],
    "interfaces": [],
    "possible_types": null
  }
}

The server implements in-memory caching with the following characteristics:

• Cache Duration: 5 minutes
• Cache Key: Combination of endpoint URL and authentication method
• Automatic Invalidation: Expired entries are automatically removed
• Performance: Subsequent requests to the same endpoint return cached data instantly

The server provides comprehensive error handling for:

• Network Issues: Connection timeouts, DNS resolution failures
• HTTP Errors: 4xx and 5xx responses from GraphQL endpoints
• GraphQL Errors: Schema validation errors, introspection failures
• Authentication Errors: Invalid credentials, expired tokens
• Validation Errors: Missing required parameters, invalid type names

npm run build

npm run dev

npm run clean
npm run build

• Default Endpoint: http://localhost:5555/graphql
• Cache Duration: 5 minutes (300 seconds)
• Timeout: Uses fetch default timeout
• Max Cache Size: No limit (memory permitting)

1. Use Detailed Mode: Set detailed: true when you need comprehensive information
2. Filter Effectively: Use search patterns to reduce response size
3. Cache Awareness: Subsequent calls to the same endpoint will be faster due to caching
4. Error Handling: Always check the success field in responses

1. Specific Searches: Use specific search terms to reduce response size
2. Type Filtering: Use the kind parameter when filtering types
3. Summary Mode: Use detailed: false for quick overviews
4. Endpoint Reuse: Reuse the same endpoint URL to benefit from caching

Schema not found

• Verify the GraphQL endpoint URL is correct
• Check if the endpoint requires authentication
• Ensure the endpoint supports introspection queries

Authentication failures

• Verify credentials are correct
• Check if the endpoint expects Basic Auth or Bearer tokens
• Ensure tokens haven't expired

Network timeouts

• Check network connectivity to the GraphQL endpoint
• Verify firewall settings allow outbound connections
• Consider if the GraphQL server is running and responsive

Enable debug logging by setting the environment variable:

export DEBUG=graphql-introspection:*

MIT License - see LICENSE file for details.