🚀 MCP GraphQL Query Generator

License: MIT TypeScript Bun VS Code GitHub Copilot

A smart Model Context Protocol (MCP) server that automatically discovers and generates GraphQL queries for any API. Works with VS Code + GitHub Copilot, CLI, and REST API to make exploring and using GraphQL APIs effortless.

Perfect for VS Code integration with GitHub Copilot! 🤖

Quick Start • Features • VS Code Setup • API Reference • Examples

What is MCP?

The Model Context Protocol (MCP) is a new protocol that lets tools, APIs, and models talk to each other in a structured way. Instead of manually copying data into your IDE or chat window, MCP servers can: - Provide real-time API access directly inside VS Code or AI tools. - Enable natural language queries ("show me all products with pagination"). - Act as connectors between AI assistants (like Copilot) and external systems. This project is an MCP server for GraphQL APIs: - It introspects any GraphQL schema. - Generates queries automatically. - Exposes them through CLI, REST, and VS Code integration. In short: you don’t need to handcraft GraphQL queries anymore — just ask, and they’re generated for you.

What is this?

This tool automatically introspects any GraphQL API and generates intelligent, production-ready queries with:

Auto-discovery of all available queries and types in your GraphQL API
Smart field selecion, including nested types
Table-formatted queries with pagination, filtering, and sorting
Natural language integration with GitHub Copilot
Zero configuration - just point it to your GraphQL endpoint
Multi-auth support (Bearer, API Key, Keycloak, etc.)
Multiple interfaces (CLI, REST API, MCP Server, Web UI)

Features

For Developers

Instant GraphQL exploration - No need to read documentation
Smart query generation - Automatically includes relevant fields
Production-ready queries - With proper pagination and error handling
Type-safe - Full TypeScript support

For AI Integration

GitHub Copilot integration - Ask questions in natural language
VS Code extension ready - Works globally across all projects
Context-aware - Understands your API structure
Intelligent suggestions - Based on your schema

For Teams

Consistent query patterns - Standardized across projects
Documentation generator - Auto-generates API insights
Multi-environment - Dev, staging, prod configurations
Docker ready - Easy deployment and scaling

Quick Start

Option 1: Global VS Code Installation (Recommended)

Transform VS Code into a GraphQL powerhouse in 2 minutes:

# 1. Install Bun runtime (faster than Node.js) powershell -c "irm bun.sh/install.ps1 | iex" # 2. Clone and install globally git clone https://github.com/marias1lva/mcp-graphql-generator.git cd mcp-graphql-generator .\install-global.ps1 # 3. Add to VS Code settings.json: { "mcp.servers": { "graphql-query-generator": { "name": "GraphQL Query Generator", "url": "http://localhost:3001", "enabled": true } } } # 4. Configure your API notepad %APPDATA%\MCPGraphQLServer\.env # Add: GRAPHQL_API_URL=https://your-api.example.com/graphql

That's it! Now ask GitHub Copilot: "List available GraphQL queries"

Option 2: Local Development

# Clone and setup git clone https://github.com/marias1lva/mcp-graphql-generator.git cd mcp-graphql-generator bun install # Configure API cp .env.example .env # Edit .env with your GraphQL API URL # Start MCP server bun mcp-server.ts # Or use CLI directly bun src/cli.ts list bun src/cli.ts generate listUsers

VS Code Integration

Once installed, use natural language with GitHub Copilot:

👤 "List all available GraphQL queries" 🤖 Found these queries: • listUsers - Get all users with pagination • listProducts - Browse products catalog • listOrders - View order history 👤 "Generate a query to get users with their profiles" 🤖 query ListUsers($first: Int, $after: String) { listUsers(first: $first, after: $after) { edges { node { id name email profile { firstName lastName avatar } } } pageInfo { hasNextPage endCursor } } } 👤 "What fields are available in the Product type?" 🤖 Product type fields: • id (ID!) - Unique identifier • name (String!) - Product name • price (Float!) - Product price • description (String) - Product description • category (Category) - Product category

Usage Options

1. CLI Interface

# Discover available queries bun src/cli.ts list # Generate a specific query bun src/cli.ts generate listUsers # Generate with options bun src/cli.ts generate listProducts --depth 3 --pagination # Interactive mode bun src/cli.ts interactive

2. REST API

### Get all available queries GET http://localhost:3001/mcp/queries ### Generate a specific query POST http://localhost:3001/mcp/generate-query Content-Type: application/json { "queryName": "listUsers", "options": { "includePagination": true, "maxDepth": 2, "selectedFields": ["id", "name", "email"] } } ### Analyze a type GET http://localhost:3001/mcp/analyze/User

3. Programmatic Usage

import { GenericQueryGenerator } from './src/generators/genericQueryGenerator'; const generator = new GenericQueryGenerator(); // Get available queries const queries = await generator.getAvailableQueries(); // Generate a table query const query = await generator.generateTableQuery('listUsers', { includePagination: true, maxDepth: 2 }); // Generate custom query const customQuery = await generator.generateCustomQuery('listUsers', ['id', 'name', 'email'], { includePagination: true } );

Configuration

Environment Variables

# Required: Your GraphQL API endpoint GRAPHQL_API_URL=https://your-api.example.com/graphql # Optional: Authentication API_TOKEN=your_bearer_token API_KEY=your_api_key # Optional: Keycloak authentication KEYCLOAK_CLIENT_ID=your_client_id KEYCLOAK_CLIENT_SECRET=your_client_secret KEYCLOAK_URL=https://your-keycloak.example.com/auth KEYCLOAK_REALM=your-realm # Optional: Server configuration MCP_PORT=3001 MAX_DEPTH=3

Per-Project Configuration

Create .vscode/settings.json in your project:

{ "mcpGraphQL.projectSettings": { "apiUrl": "https://project-specific-api.com/graphql", "authToken": "${env:PROJECT_API_TOKEN}", "defaultDepth": 2, "enablePagination": true } }

Examples

Example Output - List Users Query

query ListUsers($first: Int, $after: String, $orderBy: UserOrderByInput) { listUsers(first: $first, after: $after, orderBy: $orderBy) { edges { node { id name email createdAt profile { firstName lastName avatar } } } pageInfo { hasNextPage hasPreviousPage startCursor endCursor } totalCount } }

Example Output - Products with Categories

query ListProducts($first: Int, $after: String, $filters: ProductFiltersInput) { listProducts(first: $first, after: $after, filters: $filters) { edges { node { id name price description category { id name slug } images { url alt } } } pageInfo { hasNextPage endCursor } } }

Architecture

mcp-graphql-generator/ ├── src/ │ ├── cli.ts # Command line interface │ ├── app.ts # HTTP server entry point │ ├── generators/ │ │ └── genericQueryGenerator.ts # Core query generation logic │ ├── services/ │ │ ├── graphqlIntrospection.ts # API discovery service │ │ └── keycloakAuth.ts # Authentication service │ ├── mcp/ │ │ └── server.ts # MCP protocol server │ ├── config/ │ │ └── credentials.ts # Credential management │ └── types/ │ ├── auth.ts # Authentication types │ └── env.d.ts # Environment types ├── mcp-server.ts # MCP server entry point ├── install-global.ps1 # Global VS Code installation ├── configure-autostart.ps1 # Auto-start configuration ├── docker-compose.global.yml # Docker deployment └── docs/ # Additional documentation

Docker Deployment

# docker-compose.yml version: '3.8' services: mcp-server: build: . ports: - "3001:3001" environment: - GRAPHQL_API_URL=https://your-api.example.com/graphql - API_TOKEN=your_token restart: unless-stopped

# Deploy with Docker docker-compose up -d # Or with Docker directly docker build -t mcp-graphql-generator . docker run -p 3001:3001 -e GRAPHQL_API_URL=https://your-api.com/graphql mcp-graphql-generator

API Compatibility

Works with any GraphQL API that supports introspection, including:

✅ Apollo Server - Full compatibility
✅ GraphQL Yoga - Full compatibility
✅ Hasura - Including metadata queries
✅ Postgraphile - Auto-generated CRUD
✅ AWS AppSync - With custom resolvers
✅ Shopify Admin API - E-commerce queries
✅ GitHub GraphQL API - Repository data
✅ Strapi GraphQL - Headless CMS
✅ Contentful - Content management
✅ Custom GraphQL APIs - Any introspection-enabled API

Development

Setup Development Environment

# Clone repository git clone https://github.com/marias1lva/mcp-graphql-generator.git cd mcp-graphql-generator # Install dependencies bun install # Copy environment template cp .env.example .env # Edit .env with your test GraphQL API # Start in development mode bun --watch mcp-server.ts # Run CLI in development bun --watch src/cli.ts list # Build for production bun build # Run tests (when implemented) bun test

Project Scripts

{ "scripts": { "start": "bun src/app.ts", "dev": "bun --watch mcp-server.ts", "build": "bun build", "cli": "bun src/cli.ts", "cli:list": "bun src/cli.ts list", "cli:interactive": "bun src/cli.ts interactive" } }

Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Make your changes with proper TypeScript types
Test your changes with a real GraphQL API
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Contribution Guidelines

TypeScript - All code must be properly typed
Bun - Use Bun for package management and runtime
Testing - Include tests for new features
Documentation - Update README and inline docs
Code Style - Follow existing patterns

License

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

Acknowledgments

Bun - For blazing fast JavaScript runtime
Model Context Protocol - For VS Code integration standard
GraphQL - For the amazing query language
GitHub Copilot - For AI-powered development
TypeScript - For type safety and developer experience

⭐ Star this repo if it helped you! ⭐

MCP GraphQL Query Generator