Text-To-GraphQL

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.

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.

- 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

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

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

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

# 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/binon macOS/Linux, which translates to/Users/yourusername/.local/bin(replaceyourusernamewith your actual username).

# 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: Theuv runpattern automatically handles virtual environments, making MCP configuration cleaner and more reliable than traditional pip installations.

# For contributing to the project uv sync --dev

{ "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" } } }

- Replace/path/to/text-to-graphql-mcpwith the actual path to your cloned repository
- Replace/path/to/uv/binwith your actual UV installation path (typically/Users/yourusername/.local/binon macOS)
- ThePATHenvironment variable isrequiredfor MCP clients to find theuvcommand

Add to your Claude Desktop MCP configuration file:

macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%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" } } } }

- Find your UV path: Runwhich uvin terminal (typically/Users/yourusername/.local/bin/uv)
- Set the PATH: Use the directory containinguv(e.g.,/Users/yourusername/.local/bin)
- Replace paths: Update both the--directoryargument andPATHenvironment variable with your actual paths
- Add your API keys: Replace the placeholder values with your actual API keys

# 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.envfile (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

Convert natural language to GraphQL queries.

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

Validate GraphQL queries against the loaded schema.

Execute GraphQL queries and return formatted results.

Retrieve the history of all queries in the current session.

Get example queries to understand the system's capabilities.

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

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

💡 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.

# 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 .

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

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

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

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

# Start the service docker-compose up -d # View logs docker-compose logs -f # Stop the service docker-compose down

When running the MCP server in Docker, you need to usedocker execto communicate with the container:

Important: The environment variables (OPENAI_API_KEY, GRAPHQL_ENDPOINT, etc.) must be set when youfirst run the containerusing 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

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

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.

The system uses a multi-agent architecture built with LangGraph:
- Intent Recognition: Understands what the user wants to accomplish
- Schema Management: Loads and manages GraphQL schema information
- Query Construction: Builds GraphQL queries from natural language
- Query Validation: Ensures queries are valid against the schema
- Query Execution: Executes queries against the GraphQL endpoint
- Data Visualization: Provides recommendations for visualizing results

- bearer(default): UsesAuthorization: Bearer <token>- standard for most GraphQL APIs
- apikey: UsesX-API-Key: <key>- used by some APIs like Arize
- direct: UsesAuthorization: <token>- direct token without Bearer prefix
- Custom: SetGRAPHQL_HEADERSto override with any custom authentication format

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

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

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

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

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

Visitdocs.arize.com/phoenixfor comprehensive guides on agent observability and development best practices.

# Install development dependencies uv pip install -e ".[dev]" # Run tests pytest # Format code black . isort . # Type checking mypy src/

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

We welcome contributions! Please see our contributing guidelines for details.
- Fork the repository
- Create a feature branch (git checkout -b feature/amazing-feature)
- Commit your changes (git commit -m 'Add some amazing feature')
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request

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

- Issues & Bug Reports
- MCP Protocol Documentation

- Built withLangChainandLangGraph
- UsesFastMCPfor MCP server implementation

A Binary Ninja plugin, MCP server, and bridge that seamlessly integrates Binary Ninja with your favorite MCP client.