GraphQL

You can turn VS Code into a powerful GraphQL explorer with an MCP server that automatically introspects any GraphQL API, discovers available queries, and generates production-ready queries on demand. It works through multiple interfaces (CLI, REST API, MCP Server, and a VS Code integration) so you can explore, generate, and run queries without handcrafting them yourself.

How to use

You interact with the GraphQL Query Generator through an MCP client (such as VS Code integration or a CLI/REST consumer). Start by pointing the MCP server at your GraphQL endpoint. Then you can ask in natural language or by selecting a query, and the server will return a ready-to-run GraphQL query with pagination, filtering, and sorting when appropriate. In practice, you can discover all available queries, browse their fields, and generate a table-style query that includes nested types and pagination. Use Copilot in VS Code to phrase your request in plain English, and the server will translate it into a production-ready GraphQL query.

Typical workflows include discovering what queries exist, generating a listUsers query with pagination, and requesting a product catalog query with nested fields like profiles or categories. You can also analyze a type to see field names and available subfields, helping you construct precise queries without manual schema inspection.

How to install

Prerequisites: ensure you have a runtime for running MCP servers. This setup uses Bun for speed and simplicity, but you can also run the server locally with the provided development commands.

Option A – 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

Option B – Local development Start from a clean clone, install dependencies with Bun, configure your API URL, and run the local MCP server.

# 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

Configuration and usage notes

Configure the GraphQL endpoint and authentication as needed. The server supports multiple authentication schemes (Bearer tokens, API keys, Keycloak, etc.) and can be reached via HTTP (remote server) or STDIO (local process) interfaces.

# Example environment for the HTTP MCP server
GRAPHQL_API_URL=https://your-api.example.com/graphql
# Optional authentication
API_TOKEN=your_bearer_token
API_KEY=your_api_key

# Server port and depth controls
MCP_PORT=3001
MAX_DEPTH=3

Per-project customization allows you to set project-specific API endpoints, auth tokens, and default depth for query generation. You can place these settings in a project-specific VS Code settings file or pass them through environment variables when starting the server.

Examples

Commonly generated queries show a list of fields with nested structures and pagination information. Here is an illustrative example of what a generated query for users might look like, including their profiles and pagination metadata.

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

Another example shows a products query with category and images.

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

Usage options

You can access the MCP server through a REST API, a CLI, or directly via the MCP protocol from a client. The CLI lets you list available queries, generate specific queries, and run interactive sessions to refine your selections. The REST API exposes endpoints to retrieve available queries, generate queries, and analyze types.

Security and environment

Keep your API credentials secure. Use environment variables or secret managers for tokens. The server supports multiple authentication methods and can operate behind secure networks with proper TLS/HTTPS configuration when exposed publicly.

Troubleshooting and tips

If you cannot reach the GraphQL endpoint, verify the GRAPHQL_API_URL value and network access. Check that MCP_PORT is not in use and that the server process has permission to bind to the port. When the server starts, monitor the console for generated query lists and any error messages related to schema introspection or authentication.

Notes on deployment

You can deploy the MCP GraphQL Generator with Docker by building the container and exposing port 3001, then passing the GraphQL API URL and optional token as environment variables. Ensure the endpoint is reachable from the deployment environment.

Available tools

GraphQL query generation

Automatically discovers and generates production-ready GraphQL queries with smart field selection, pagination, and error handling.

Auto-discovery

Introspects the GraphQL schema to list all available queries and types.

Pagination and sorting

Generates queries with pagination controls and sorting options for table-like results.

Natural language integration

Supports natural language prompts to generate queries through Copilot and IDE integration.

REST API access

Exposes endpoints to list, generate, and analyze queries via a REST interface.

CLI interface

Command-line tools to list available queries, generate specific queries, and run interactive sessions.

Docker deployment

Docker-ready deployment for scalable environments.