Arize-ai/text-to-graphql-mcp

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.
🚀 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:**
**Windows:**
**Find your UV installation path:**
> **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
> **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):**
**Development Setup:**
🏃‍♂️ Quick Start
1. Configure with Cursor (Recommended)
Add to your .cursor/mcp.json:
> **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
> **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
4. Alternative: Use Environment Variables
If you prefer using a .env file (useful for local development):
Then use a simplified MCP configuration (still requires PATH):
5. Run the MCP Server (Optional - for testing)
🔧 Usage
Available MCP Tools
generate_graphql_query
Convert natural language to GraphQL queries.
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:**
**Generated GraphQL:**
🐳 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.