Text-To-GraphQL

MCP server for text-to-graphql, integrates with Claude Desktop and Cursor.

View on GitHub →

Text-to-GraphQL MCP Server

Transform natural language queries into GraphQL queries using an MCP (Model Context Protocol) server that integrates seamlessly with AI assistants like Claude Desktop and Cursor.

Install MCP Server

Claude Demo

🚀 Overview

The Text-to-GraphQL MCP Server converts natural language descriptions into valid GraphQL queries using an AI agent built with LangGraph. It provides a bridge between human language and GraphQL APIs, making database and API interactions more intuitive for developers and non-technical users alike.

✨ Features

  • Natural Language to GraphQL: Convert plain English queries to valid GraphQL
  • Schema Management: Load and introspect GraphQL schemas automatically
  • Query Validation: Validate generated queries against loaded schemas
  • Query Execution: Execute queries against GraphQL endpoints with authentication
  • Query History: Track and manage query history across sessions
  • MCP Protocol: Full compatibility with Claude Desktop, Cursor, and other MCP clients
  • Error Handling: Graceful error handling with detailed debugging information
  • Caching: Built-in caching for schemas and frequently used queries

🛠 Installation

Prerequisites: Install UV (Recommended)

UV is a fast Python package installer and resolver. Install it first:

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

Find your UV installation path:

# Find where uv is installed
which uv

# Common locations:
# macOS/Linux: ~/.local/bin/uv
# Windows: %APPDATA%\uv\bin\uv.exe

Important: You'll need the UV path for MCP configuration. The typical path is ~/.local/bin on macOS/Linux, which translates to /Users/yourusername/.local/bin (replace yourusername with your actual username).

Setup for MCP Usage

# Clone the repository
git clone https://github.com/Arize-ai/text-to-graphql-mcp.git
cd text-to-graphql-mcp

# Install dependencies (UV automatically creates virtual environment)
uv sync

# Test the installation
uv run text-to-graphql-mcp --help

Note: The uv run pattern automatically handles virtual environments, making MCP configuration cleaner and more reliable than traditional pip installations.

Alternative Installation Methods

From PyPI (when published):

pip install text-to-graphql-mcp

Development Setup:

# For contributing to the project
uv sync --dev

🏃‍♂️ Quick Start

1. Configure with Cursor (Recommended)

Add to your .cursor/mcp.json:

{
  "text-to-graphql": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/text-to-graphql-mcp",
      "run",
      "text-to-graphql-mcp"
    ],
    "env": {
      "PATH": "/path/to/uv/bin:/usr/bin:/bin",
      "OPENAI_API_KEY": "your_openai_api_key_here",
      "GRAPHQL_ENDPOINT": "https://your-graphql-api.com/graphql",
      "GRAPHQL_API_KEY": "your_api_key_here",
      "GRAPHQL_AUTH_TYPE": "bearer"
    }
  }
}

Important Setup Notes:

  • Replace /path/to/text-to-graphql-mcp with the actual path to your cloned repository
  • Replace /path/to/uv/bin with your actual UV installation path (typically /Users/yourusername/.local/bin on macOS)
  • The PATH environment variable is required for MCP clients to find the uv command

2. Configure with Claude Desktop

Add to your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "text-to-graphql": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/text-to-graphql-mcp",
        "run",
        "text-to-graphql-mcp"
      ],
      "env": {
        "PATH": "/path/to/uv/bin:/usr/bin:/bin",
        "OPENAI_API_KEY": "your_openai_api_key_here",
        "GRAPHQL_ENDPOINT": "https://your-graphql-api.com/graphql",
        "GRAPHQL_API_KEY": "your_api_key_here",
        "GRAPHQL_AUTH_TYPE": "bearer"
      }
    }
  }
}

Setup Instructions:

  1. Find your UV path: Run which uv in terminal (typically /Users/yourusername/.local/bin/uv)
  2. Set the PATH: Use the directory containing uv (e.g., /Users/yourusername/.local/bin)
  3. Replace paths: Update both the --directory argument and PATH environment variable with your actual paths
  4. Add your API keys: Replace the placeholder values with your actual API keys

3. Common UV Path Examples

# Find your UV installation
which uv

# Common paths by OS:
# macOS: /Users/yourusername/.local/bin/uv
# Linux: /home/yourusername/.local/bin/uv  
# Windows: C:\Users\yourusername\AppData\Roaming\uv\bin\uv.exe

# For MCP config, use the directory path:
# macOS: /Users/yourusername/.local/bin
# Linux: /home/yourusername/.local/bin
# Windows: C:\Users\yourusername\AppData\Roaming\uv\bin

4. Alternative: Use Environment Variables

If you prefer using a .env file (useful for local development):

# Required
OPENAI_API_KEY=your_openai_api_key_here
GRAPHQL_ENDPOINT=https://your-graphql-api.com/graphql
GRAPHQL_API_KEY=your_api_key_here

# Optional - Authentication method (bearer|apikey|direct)
GRAPHQL_AUTH_TYPE=bearer

# Optional - Model settings
MODEL_NAME=gpt-4o
MODEL_TEMPERATURE=0

Then use a simplified MCP configuration (still requires PATH):

{
  "text-to-graphql": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/text-to-graphql-mcp",
      "run",
      "text-to-graphql-mcp"
    ],
    "env": {
      "PATH": "/path/to/uv/bin:/usr/bin:/bin"
    }
  }
}

5. Run the MCP Server (Optional - for testing)

# Run the server directly for testing
text-to-graphql-mcp

# Or run as a module
python -m text_to_graphql_mcp.mcp_server

🔧 Usage

Available MCP Tools

generate_graphql_query

Convert natural language to GraphQL queries.

Input: "Get all users with their names and emails"
Output: query { users { id name email } }

validate_graphql_query

Validate GraphQL queries against the loaded schema.

execute_graphql_query

Execute GraphQL queries and return formatted results.

get_query_history

Retrieve the history of all queries in the current session.

get_query_examples

Get example queries to understand the system's capabilities.

Example Interactions

Natural Language Input:

"Show me all blog posts from the last week with their authors and comment counts"

Generated GraphQL:

query {
  posts(where: { createdAt: { gte: "2024-06-05T00:00:00Z" } }) {
    id
    title
    content
    createdAt
    author {
      id
      name
      email
    }
    comments {
      id
    }
    _count {
      comments
    }
  }
}

🐳 Deploying with Docker

💡 Key Concept: When using Docker with MCP clients (Claude/Cursor), environment variables are set during container startup (docker run), not in the MCP client configuration. The MCP clients simply connect to the already-running container.

Building the Docker Image

# Clone the repository
git clone https://github.com/Arize-ai/text-to-graphql-mcp.git
cd text-to-graphql-mcp

# Build the Docker image
docker build -t text-to-graphql-mcp .

Running the Container

Method 1: Using Environment Variables Directly

docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  -e OPENAI_API_KEY="your_openai_api_key_here" \
  -e GRAPHQL_ENDPOINT="https://your-graphql-api.com/graphql" \
  -e GRAPHQL_API_KEY="your_api_key_here" \
  -e GRAPHQL_AUTH_TYPE="bearer" \
  -e MODEL_NAME="gpt-4o" \
  text-to-graphql-mcp

Method 2: Using an Environment File

Create a .env file:

OPENAI_API_KEY=your_openai_api_key_here
GRAPHQL_ENDPOINT=https://your-graphql-api.com/graphql
GRAPHQL_API_KEY=your_api_key_here
GRAPHQL_AUTH_TYPE=bearer
MODEL_NAME=gpt-4o
MODEL_TEMPERATURE=0

Run the container:

docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  --env-file .env \
  text-to-graphql-mcp

Method 3: Using Docker Compose

Create a docker-compose.yml file:

version: '3.8'

services:
  text-to-graphql-mcp:
    build: .
    container_name: text-to-graphql-mcp
    ports:
      - "8000:8000"
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}
      - GRAPHQL_ENDPOINT=${GRAPHQL_ENDPOINT}
      - GRAPHQL_API_KEY=${GRAPHQL_API_KEY}
      - GRAPHQL_AUTH_TYPE=${GRAPHQL_AUTH_TYPE:-bearer}
      - MODEL_NAME=${MODEL_NAME:-gpt-4o}
      - MODEL_TEMPERATURE=${MODEL_TEMPERATURE:-0}
      - API_HOST=0.0.0.0  # Important: bind to all interfaces in container
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

Then run:

# Start the service
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the service
docker-compose down

Using Docker with MCP Clients

When running the MCP server in Docker, you need to use docker exec to communicate with the container:

Important: The environment variables (OPENAI_API_KEY, GRAPHQL_ENDPOINT, etc.) must be set when you first run the container using one of the methods above. The MCP client configurations below only connect to an already-running container.

Step 1: First, ensure your container is running with environment variables

# Example: Make sure the container is running with your environment variables
docker run -d \
  --name text-to-graphql-mcp \
  -p 8000:8000 \
  --env-file .env \
  text-to-graphql-mcp

# Verify the container is running
docker ps | grep text-to-graphql-mcp

Step 2: Configure Cursor

Add to .cursor/mcp.json:

{
  "text-to-graphql": {
    "command": "docker",
    "args": [
      "exec",
      "-i",
      "text-to-graphql-mcp",
      "uv",
      "run",
      "python",
      "-m",
      "src.text_to_graphql_mcp.mcp_server"
    ]
  }
}

Step 2: Configure Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "text-to-graphql": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "text-to-graphql-mcp",
        "uv",
        "run",
        "python",
        "-m",
        "src.text_to_graphql_mcp.mcp_server"
      ]
    }
  }
}

Note: The MCP client configurations don't need environment variables because they're connecting to a container that already has them set. If you restart the container, make sure to include the environment variables again.

🏗 Architecture

The system uses a multi-agent architecture built with LangGraph:

  1. Intent Recognition: Understands what the user wants to accomplish
  2. Schema Management: Loads and manages GraphQL schema information
  3. Query Construction: Builds GraphQL queries from natural language
  4. Query Validation: Ensures queries are valid against the schema
  5. Query Execution: Executes queries against the GraphQL endpoint
  6. Data Visualization: Provides recommendations for visualizing results

⚙️ Configuration

Environment Variables

VariableDescriptionDefault
OPENAI_API_KEYOpenAI API key for LLM operationsRequired
GRAPHQL_ENDPOINTGraphQL API endpoint URLRequired
GRAPHQL_API_KEYAPI key for your GraphQL serviceRequired
GRAPHQL_AUTH_TYPEAuthentication method: bearer, apikey, or directbearer
GRAPHQL_HEADERSCustom headers as JSON (overrides auto-auth){}
MODEL_NAMEOpenAI model to usegpt-4o
MODEL_TEMPERATUREModel temperature for responses0
API_HOSTServer host address127.0.0.1
API_PORTServer port8000
RECURSION_LIMITMax recursion for agent workflow10

Authentication Types

  • bearer (default): Uses Authorization: Bearer <token> - standard for most GraphQL APIs
  • apikey: Uses X-API-Key: <key> - used by some APIs like Arize
  • direct: Uses Authorization: <token> - direct token without Bearer prefix
  • Custom: Set GRAPHQL_HEADERS to override with any custom authentication format

Common GraphQL API Examples

GitHub GraphQL API:

GRAPHQL_ENDPOINT=https://api.github.com/graphql
GRAPHQL_API_KEY=ghp_your_github_personal_access_token
GRAPHQL_AUTH_TYPE=bearer

Shopify GraphQL API:

GRAPHQL_ENDPOINT=https://your-shop.myshopify.com/admin/api/2023-10/graphql.json
GRAPHQL_API_KEY=your_shopify_access_token
GRAPHQL_AUTH_TYPE=bearer

Arize GraphQL API:

GRAPHQL_ENDPOINT=https://app.arize.com/graphql
GRAPHQL_API_KEY=your_arize_developer_api_key
# Auth type auto-detected for Arize

Hasura:

GRAPHQL_ENDPOINT=https://your-app.hasura.app/v1/graphql
GRAPHQL_HEADERS={"x-hasura-admin-secret": "your_admin_secret"}

🔍 Observability & Agent Development

Want to build better AI agents quickly? Check out Arize Phoenix - an open-source observability platform specifically designed for LLM applications and agents. Phoenix provides:

  • Real-time monitoring of your agent's performance and behavior
  • Trace visualization to understand complex agent workflows
  • Evaluation frameworks for testing and improving agent responses
  • Data quality insights to identify issues with your training data
  • Cost tracking for LLM API usage optimization

Phoenix integrates seamlessly with LangChain and LangGraph (which this project uses) and can help you:

  • Debug agent behavior when queries aren't generated correctly
  • Monitor GraphQL query quality and success rates
  • Track user satisfaction and query complexity
  • Optimize your agent's prompt engineering

Get started with Phoenix:

pip install arize-phoenix
phoenix serve

Visit docs.arize.com/phoenix for comprehensive guides on agent observability and development best practices.

🧪 Development

Setup Development Environment

# Install development dependencies
uv pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .
isort .

# Type checking
mypy src/

Project Structure

text-to-graphql-mcp/
├── src/text_to_graphql_mcp/     # Main package
│   ├── mcp_server.py            # MCP server implementation
│   ├── agent.py                 # LangGraph agent logic
│   ├── config.py                # Configuration management
│   ├── logger.py                # Logging utilities
│   ├── tools/                   # Agent tools
│   └── ...
├── tests/                       # Test suite
├── docs/                        # Documentation
├── pyproject.toml              # Package configuration
└── README.md

🤝 Contributing

We welcome contributions! Please see our contributing guidelines for details.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📝 License

This project is licensed under the Elastic License 2.0 (ELv2) - see the LICENSE file for details.

🐛 Troubleshooting

Common Issues

"No module named 'text_to_graphql_mcp'"

  • Ensure you've installed the package: pip install text-to-graphql-mcp

"OpenAI API key not found"

  • Set your OPENAI_API_KEY environment variable
  • Check your .env file configuration

"GraphQL endpoint not reachable"

  • Verify your GRAPHQL_ENDPOINT URL
  • Check network connectivity and authentication

"Schema introspection failed"

  • Ensure the GraphQL endpoint supports introspection
  • Check authentication headers if required

🔗 Links

🙏 Acknowledgments

Related Servers