MCP GraphQL Forge

Quick Install

Alternative Installation Methods

# Via Smithery (recommended)
npx @smithery/cli install @toolprint/mcp-graphql-forge --client claude

# Via npm
npm install -g @toolprint/mcp-graphql-forge

An MCP server that makes GraphQL APIs accessible to AI tools by:

• Automatically generating MCP tools from GraphQL schema introspection
• Validating parameters and handling errors for reliable AI interactions
• Supporting both stdio and HTTP transports for development and production
• Caching schema and field selections for consistent performance

✨ Features

• Tool Generation: Creates MCP tools from GraphQL schema introspection
• Parameter Validation: Multi-layer validation prevents GraphQL errors
• Dual Transport: Supports stdio (AI tools) and HTTP (development/testing)
• Schema Management: Optional pre-introspection and caching
• Authentication: Flexible header configuration for authenticated endpoints [Experimental]

🚀 Getting Started

Note: Docker runtime support is currently a work in progress. For production deployments, we recommend using the TypeScript runtime on platforms like Smithery.

Quick Start with HTTP Mode (Recommended for Development)

1. Start the server:

   # Start serving it with the Streamable HTTP transport
   GRAPHQL_ENDPOINT="https://your-api.com/graphql" npx -y @toolprint/mcp-graphql-forge --transport http --port 3001

2. Connect with MCP Inspector:

   # In another terminal, launch the inspector
   npx @modelcontextprotocol/inspector

3. With authentication:

   # Using environment variables for configuration
   export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
   export GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN"
   npx @toolprint/mcp-graphql-forge --transport http --port 3001
   
   # Or all in one line
   GRAPHQL_ENDPOINT="https://api.github.com/graphql" GRAPHQL_AUTH_HEADER="Bearer YOUR_TOKEN" npx @toolprint/mcp-graphql-forge --transport http --port 3001

Direct AI Integration (Claude/Cursor)

Create an mcp.json in your project root. This will run it in stdio mode.

{
    "mcpServers": {
        "mcp-graphql-forge": {
            "command": "npx",
            "args": [
              "-y",
              "@toolprint/mcp-graphql-forge"
            ],
            "env": {
                "GRAPHQL_ENDPOINT": "https://your-api.com/graphql",
                "GRAPHQL_AUTH_HEADER": "Bearer YOUR_TOKEN"
            }
        }
    }
}

Schema Management

1. Pre-generate schema:

   # Generate schema without starting server
   GRAPHQL_ENDPOINT="https://your-api.com/graphql" mcp-graphql-forge introspect
   
   # Start server using pre-generated schema
   mcp-graphql-forge --no-introspection --transport http --port 3001

2. Custom schema location:

   # Generate schema in custom location
   SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge introspect
   
   # Use custom schema location
   SCHEMA_PATH="./schemas/my-api.json" mcp-graphql-forge --no-introspection --transport http --port 3001

3. Force schema regeneration:

   # Force regenerate schema even if it exists
   mcp-graphql-forge introspect --force
   
   # Regenerate and start server
   mcp-graphql-forge --force-introspection --transport http --port 3001

Advanced Configuration

# Multiple custom headers
export GRAPHQL_HEADER_X_API_KEY="your-api-key"
export GRAPHQL_HEADER_X_CLIENT_ID="your-client-id"
mcp-graphql-forge --transport http --port 3001

# Development mode with auto-reload on schema changes
mcp-graphql-forge --transport http --port 3001 --watch

🛠️ How It Works

1. Schema Introspection

🗂️  Building field selection cache for all types...
📊 Generated field selections for 44 types  
💾 Field selection cache contains 44 full selections and 5 minimal selections
Generated 63 tools from GraphQL schema:
  - 30 query tools
  - 33 mutation tools

2. Intelligent Tool Generation

For a GraphQL schema like:

type Query {
  user(id: ID!): User
  articles(filters: ArticleFiltersInput, pagination: PaginationArg): [Article]
}

type Mutation {
  createUser(input: CreateUserInput!): User
}

Fast MCP GraphQL automatically generates:

• ✅ query_user - with required id parameter validation
• ✅ query_articles - with optional filtering and pagination
• ✅ mutation_createUser - with input validation and complete field selections

3. Smart Field Selection

Instead of manual GraphQL query construction:

# ❌ Error-prone manual approach
query {
  articles {
    # Missing required field selections!
    author {
      # Circular reference issues!
    }
  }
}

Fast MCP GraphQL generates optimal queries automatically:

# ✅ Auto-generated with full field selections
query articlesOperation($filters: ArticleFiltersInput, $pagination: PaginationArg) {
  articles(filters: $filters, pagination: $pagination) {
    documentId
    title
    description
    author {
      documentId
      name
      email
      articles_connection {
        nodes { documentId }  # Circular reference handled!
      }
    }
    category {
      documentId
      name
      articles { documentId }  # Cached selection reused!
    }
  }
}

🏗️ Architecture

Caching System

• Type-Level Caching: Each GraphQL type's field selection is computed once and reused
• Circular Reference Resolution: Intelligent detection with minimal field fallbacks
• Consistent Output: Same type always generates identical field selections

Validation Pipeline

1. JSON Schema Validation: MCP clients validate parameters before execution
2. Server-Side Validation: Prevents execution with missing required parameters
3. GraphQL Validation: Final validation at the GraphQL layer

Transport Support

• Stdio Transport: For MCP client integration (default)
• HTTP Transport: RESTful interface with MCP 2025 Streamable HTTP specification
• Session Management: Automatic session handling for HTTP transport

📚 API Reference

CLI Options

mcp-graphql-forge [options]

Options:
  --transport <type>     Transport type: stdio or http (default: stdio)
  --port <number>        Port for HTTP transport (default: 3000)
  --no-introspection     Skip schema introspection (use cached schema)
  --version              Show version number
  --help                 Show help

Environment Variables

Generated Tool Schema

Each generated tool follows this pattern:

{
  name: "query_user",
  description: "Execute GraphQL query: user",
  inputSchema: {
    type: "object",
    properties: {
      id: { type: "string" }
    },
    required: ["id"]  // Only truly required parameters
  }
}

🧪 Testing

Comprehensive Test Suite

• 40+ Test Cases: Covering all functionality and edge cases
• Real-World Scenarios: Tests against actual GraphQL schemas (Strapi, GitHub, etc.)
• Security Testing: Prototype pollution protection and input validation
• Performance Testing: Cache efficiency and field selection optimization

# Run all tests
npm test

# Run specific test suites
npm test -- src/__tests__/field-selection-cache.test.ts
npm test -- src/__tests__/server-validation.test.ts
npm test -- src/__tests__/graphql-execution.test.ts

# Coverage report
npm run test:coverage

Integration Testing

# Test with real GraphQL endpoints
GRAPHQL_ENDPOINT="https://countries.trevorblades.com/" npm test

# Test caching performance
npm run test:performance

🛡️ Security

Parameter Validation

• Required Parameter Enforcement: Prevents GraphQL variable errors
• Null/Undefined Checking: Validates parameter presence and values
• Prototype Pollution Protection: Uses secure property checking methods

Schema Security

• Input Sanitization: All GraphQL inputs are properly typed and validated
• Circular Reference Protection: Prevents infinite recursion in field selections
• Header Validation: Secure header handling for authentication

🚀 Performance

Benchmarks

• Schema Introspection: ~10ms for typical schemas
• Tool Generation: ~5ms with caching enabled
• Field Selection: Pre-computed and cached for instant access
• Memory Usage: Efficient caching with minimal memory footprint

Optimization Features

• Field Selection Caching: Eliminates redundant field selection computation
• Schema Caching: Optional schema persistence for faster restarts
• Minimal GraphQL Queries: Only requests necessary fields
• Connection Pooling: Efficient HTTP client management

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

# Clone the repository
git clone https://github.com/toolprint/mcp-graphql-forge.git
cd mcp-graphql-forge

# Install dependencies
npm install

# Run tests
npm test

# Start development
npm run dev

Code Quality

• TypeScript: Fully typed codebase
• ESLint: Consistent code formatting
• Vitest: Modern testing framework
• 100% Test Coverage: Comprehensive test suite

📖 Examples

Real-World Usage

# Connect to Strapi GraphQL API
export GRAPHQL_ENDPOINT="https://your-strapi.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_STRAPI_TOKEN"
mcp-graphql-forge

# Generates tools like:
# - query_articles, query_users, query_categories
# - mutation_createArticle, mutation_updateUser
# - Full field selections with media, relations, and metadata

# Connect to GitHub GraphQL API
export GRAPHQL_ENDPOINT="https://api.github.com/graphql"
export GRAPHQL_AUTH_HEADER="Bearer YOUR_GITHUB_TOKEN"
mcp-graphql-forge

# Generates tools like:
# - query_repository, query_user, query_organization
# - query_search (with intelligent result type handling)
# - mutation_createIssue, mutation_addComment

# Connect to Shopify/WooCommerce GraphQL
export GRAPHQL_ENDPOINT="https://your-shop.myshopify.com/api/graphql"
export GRAPHQL_HEADER_X_SHOPIFY_ACCESS_TOKEN="YOUR_TOKEN"
mcp-graphql-forge

# Generates tools for:
# - Product management (query_products, mutation_productCreate)
# - Order processing (query_orders, mutation_orderUpdate)
# - Customer management with full relationship mapping

Custom Schema Example

// Example: Blog Platform Schema
type Query {
  posts(published: Boolean, authorId: ID): [Post]
  post(slug: String!): Post
  authors: [Author]
}

type Mutation {
  createPost(input: CreatePostInput!): Post
  publishPost(id: ID!): Post
}

// Generated Tools:
// ✅ query_posts (published?: boolean, authorId?: string)
// ✅ query_post (slug: string) ← Required parameter enforced
// ✅ query_authors () ← No parameters
// ✅ mutation_createPost (input: CreatePostInput) ← Validated input
// ✅ mutation_publishPost (id: string) ← Required parameter enforced

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🏢 About OneGrep, Inc.

MCP GraphQL Forge is developed and maintained by OneGrep, Inc., a company focused on building developer tools and AI infrastructure.

Issues • Discussions

Made with ❤️ by the OneGrep team