# Graphql Mcp Bridge

> A bridge implementation connecting GraphQL APIs with the Model Context Protocol (MCP), enabling seamless integration between GraphQL services and MCP-compatible AI systems. This tool facilitates data exchange and API communication by translating GraphQL operations into MCP-compatible formats.

- **Type:** MCP server
- **Install:** `agentstack add mcp-pshaddel-graphql-mcp-bridge`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [pshaddel](https://agentstack.voostack.com/s/pshaddel)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** ISC
- **Upstream author:** [pshaddel](https://github.com/pshaddel)
- **Source:** https://github.com/pshaddel/graphql-mcp-bridge
- **Website:** https://pshaddel.github.io/graphql-mcp-bridge/

## Install

```sh
agentstack add mcp-pshaddel-graphql-mcp-bridge
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

---
layout: default
title: Home
nav_order: 1
description: "A powerful bridge implementation connecting GraphQL APIs with the Model Context Protocol"
permalink: /
---

# GraphQL MCP Bridge
{: .no_toc }

[](https://github.com/pshaddel/graphql-mcp-bridge/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[](https://codecov.io/github/pshaddel/graphql-mcp-bridge)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://www.npmjs.com/package/graphql-mcp-bridge)

  

A powerful bridge implementation connecting GraphQL APIs with the Model Context Protocol (MCP), enabling seamless integration between GraphQL services and MCP-compatible AI systems. Transform any GraphQL schema into type-safe, validated MCP tools with intelligent field selection and comprehensive runtime validation powered by Zod.

## Table of Contents
{: .no_toc .text-delta }

1. TOC
{:toc}

## Features

- 🔗 **GraphQL to MCP Bridge**: Convert GraphQL schemas to MCP-compatible function definitions
- 📝 **Description Preservation**: Automatically preserves GraphQL field descriptions as tool descriptions
- ⚙️ **Flexible Configuration**: Selective operation generation with customizable naming patterns
- 🛡️ **Comprehensive Zod Validation**: Input validation and output field selection validation
- 🎯 **Smart Field Selection**: Dynamic field selection with support for nested objects, unions, and interfaces
- 🚀 **Query Generation**: Automatic GraphQL query string generation with variable handling
- 📝 **TypeScript Support**: Full TypeScript support with comprehensive type definitions
- ⚙️ **Advanced Schema Support**: Handles enums, interfaces, unions, complex inputs, and nested types
- ⚡ **Runtime Safety**: Built-in validation for all operations before execution

## Quick Start

```typescript
import { schemaParser } from 'graphql-mcp-bridge';

// Define your GraphQL schema
const schema = `
  type User {
    id: ID!
    username: String!
    email: String!
    posts: [Post!]!
  }

  type Post {
    id: ID!
    title: String!
    content: String!
    author: User!
  }

  type Query {
    """
    Retrieves a user by their unique identifier
    """
    user(id: ID!): User

    """
    Lists all users with pagination support
    """
    users(limit: Int = 10, offset: Int = 0): [User!]!
  }
`;

// Convert to MCP tools (queries only by default)
const tools = await schemaParser(schema);

// Use the generated tools
const userTool = tools.find(tool => tool.name === 'user');

// The tool automatically validates inputs and field selections
const result = await userTool.execution(
  { id: "123" }, // Variables - validated against input schema
  { id: true, username: true, posts: { title: true } } // Field selection - validated against output schema
);

console.log(result.query);
// Output: query user($id: ID!) { user(id: $id) { id username posts { title } } }
```

## Documentation

### 📚 Complete Documentation

- **[Getting Started](https://pshaddel.github.io/graphql-mcp-bridge/docs/getting-started.html)** - Installation, quick start, and basic usage examples
- **[Configuration](https://pshaddel.github.io/graphql-mcp-bridge/docs/configuration.html)** - Comprehensive configuration options and customization
- **[Validation System](https://pshaddel.github.io/graphql-mcp-bridge/docs/validation.html)** - Input validation, output validation, and error handling
- **[Advanced Usage](https://pshaddel.github.io/graphql-mcp-bridge/docs/advanced-usage.html)** - Complex examples, integration patterns, and advanced features
- **[Optimization Guide](https://pshaddel.github.io/graphql-mcp-bridge/docs/optimization.html)** - Memory optimization and performance tips for large schemas

> 📖 **Alternative Access**: If the links above don't work, you can also browse the documentation files directly in the [`docs/` folder](https://github.com/pshaddel/graphql-mcp-bridge/tree/main/docs) on GitHub.

### 🚀 Key Topics

- **Schema Conversion**: Transform GraphQL schemas into MCP-compatible tools
- **Type Safety**: Comprehensive validation with Zod for both inputs and outputs
- **Flexible Configuration**: Control which operations are generated and how they're named
- **Large Schema Support**: Handle massive schemas like GitHub's GraphQL API efficiently
- **Integration Patterns**: Best practices for integrating with MCP servers

## Installation

```bash
npm install graphql-mcp-bridge
# or
pnpm install graphql-mcp-bridge
# or
yarn add graphql-mcp-bridge
```

## Why GraphQL MCP Bridge?

GraphQL MCP Bridge solves the challenge of connecting GraphQL APIs with AI systems through the Model Context Protocol. It provides:

1. **Automatic Tool Generation**: Convert any GraphQL schema into MCP tools without manual mapping
2. **Type Safety**: Full runtime validation ensures your AI systems interact with GraphQL APIs safely
3. **Intelligent Field Selection**: Prevent over-fetching by validating field selections against your schema
4. **Production Ready**: Handle large, complex schemas with memory optimization and performance features
5. **Developer Experience**: Full TypeScript support with comprehensive error handling

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [pshaddel](https://github.com/pshaddel)
- **Source:** [pshaddel/graphql-mcp-bridge](https://github.com/pshaddel/graphql-mcp-bridge)
- **License:** ISC
- **Homepage:** https://pshaddel.github.io/graphql-mcp-bridge/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-pshaddel-graphql-mcp-bridge
- Seller: https://agentstack.voostack.com/s/pshaddel
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.