GraphQL Sales Server

A Model Context Protocol (MCP) server that provides access to sales data through GraphQL queries. This server allows AI assistants like Claude to interact with a Northwind-style sales database through natural language queries.

🚀 Features

• GraphQL API with comprehensive sales data queries
• MCP Server compatible with Claude Desktop and other MCP clients
• Rich Analytics including customer summaries, product analytics, and order statistics
• Date-based Filtering for time-range queries
• FastMCP integration for easy tool development

📊 Available Data & Queries

Core Entities

• Orders - Complete order information with details, shipping, and line items
• Customers - Customer information and purchase history
• Products - Product catalog with pricing and sales data
• Employees - Employee information linked to orders

Query Capabilities

• Get all orders or specific orders by ID
• Filter orders by customer (name or ID)
• Calculate customer spending totals and order counts
• Generate sales summaries for customers and products
• Date-range filtering and analytics
• Top products by quantity or revenue

🛠 Installation & Setup

Prerequisites

• Python 3.8 or higher
• uv package manager
• Claude Desktop (for MCP integration)

1. Clone the Repository

git clone https://github.com/JamBelg/MCP-graphql-Claude.git
cd mcp-graphql-sales-server

2. Set up Python Environment

# Create virtual environment and install dependencies
uv venv
uv pip install -r requirements.txt

3. Prepare Data

Ensure you have your sales data file at sales/data.json. The data should follow the Northwind database structure with orders containing:

{
  "Order Details": {
    "Order ID": "10248",
    "Order Date": "1996-07-04",
    "Total Price": "440.00"
  },
  "Customer Details": {
    "Customer ID": "VINET",
    "Customer Name": "Vins et alcools Chevalier"
  },
  "Products": [
    {
      "Product": "Queso Cabrales",
      "Quantity": 12,
      "Unit Price": 14.0,
      "Total": 168.0
    }
  ]
}

4. Environment Configuration

Create a .env file (optional):

GRAPHQL_ENDPOINT=http://127.0.0.1:5001/graphql
LOG_LEVEL=INFO

🚦 Running the Application

Option 1: Start Both Servers

Terminal 1 - GraphQL Server:

python graphql_client/client.py

Terminal 2 - MCP Server:

python main.py

Option 2: Using uv

# GraphQL Server
uv run graphql_client/client.py

# MCP Server  
uv run main.py

🔌 Claude Desktop Integration

1. Locate Claude Desktop Config

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

2. Add MCP Server Configuration

{
  "mcpServers": {
    "sales-graphql": {
      "command": "/path/to/.local/bin/uv",
      "args": [
        "--directory",
        "/full/path/to/mcp-graphql-sales-server",
        "run",
        "main.py"
      ]
    }
  }
}

Important: Replace /full/path/to/mcp-graphql-sales-server with the actual absolute path to your project directory.

3. Restart Claude Desktop

Completely quit and restart Claude Desktop to load the new configuration.

💬 Usage Examples

Once integrated with Claude Desktop, you can ask questions like:

"Can you get all orders from the sales database?"
"Show me orders for customer 'ALFKI'"
"What's the total spent by customer 'Antonio Moreno'?"
"Get me the top 10 customers by sales volume"
"Show me order summary statistics"
"Find all orders from July 1996"
"Which products sell the most by quantity?"

📊 Live Demo - Interactive Sales Report

Check out this interactive visualization showing the top 10 customers by sales and order count: Top 10 Customers Sales Report

This report demonstrates the kind of rich analytics and visualizations you can generate using this MCP server with Claude's data analysis capabilities.

🔍 GraphQL Playground

Access the GraphQL playground at: http://127.0.0.1:5001/graphql

Example Queries

# Get comprehensive order statistics
{
  orderSummaryStats {
    totalOrders
    totalRevenue
    uniqueCustomers
    averageOrderValue
    dateRange
  }
}

# Get customer sales summary
{
  customersSalesSummary(limit: 5, sortBy: TOTAL_SALES) {
    customerName
    totalSales
    orderCount
  }
}

# Get specific customer's orders
{
  ordersByCustomerName(customerName: "Alfreds Futterkiste") {
    orderDetails {
      orderId
      orderDate
      totalPrice
    }
    products {
      product
      quantity
      unitPrice
      total
    }
  }
}

📁 Project Structure

mcp-graphql-sales-server/
├── README.md
├── requirements.txt
├── .env.example
├── main.py                    # Entry point
├── mcp_server/
│   ├── __init__.py
│   ├── server.py             # MCP server setup
│   └── tools/
│       ├── __init__.py
│       └── graphql_tools.py  # MCP tools for GraphQL queries
├── graphql_client/
│   ├── __init__.py
│   ├── client.py            # GraphQL server & schema
│   └── queries.py           # Additional GraphQL utilities
├── config/
│   ├── __init__.py
│   └── settings.py          # Configuration management
├── sales/
│   └── data.json           # Sales data file
└── tests/
    └── test_tools.py

🛠 Available MCP Tools

The server provides these tools for AI interaction:

• graphql_query - Execute raw GraphQL queries
• test_connection - Test GraphQL endpoint connectivity
• get_all_orders - Retrieve all orders with complete details
• get_order_by_id - Get specific order by ID
• get_orders_by_customer_name - Get customer's orders by name
• get_orders_by_customer_id - Get customer's orders by ID
• get_total_spent_by_customer - Calculate customer total spending
• orders_after_date - Filter orders after specific date
• orders_between_dates - Filter orders within date range
• get_order_summary - Get comprehensive order statistics

🐛 Troubleshooting

Common Issues

1. 400 Bad Request errors: Ensure GraphQL server is running on port 5001
2. MCP tools not showing: Check Claude Desktop config path and restart the application
3. Data file errors: Verify sales/data.json exists and is properly formatted
4. Permission errors: Ensure all files are readable and paths are correct

Debug Logs

Check logs at: /tmp/mcp_sales_server.log

Testing GraphQL Directly

curl -X POST http://127.0.0.1:5001/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ orders { orderDetails { orderId } } }"}'

📄 Requirements

fastmcp>=0.9.0
requests>=2.31.0
python-dotenv>=1.0.0
flask>=2.3.0
flask-graphql>=2.0.1
graphene>=3.3.0

🤝 Contributing

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 MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with FastMCP for easy MCP server development
• Uses Graphene for GraphQL schema generation
• Inspired by the Northwind database sample data structure

---

Need help? Open an issue on GitHub or check the troubleshooting section above.