MCP Graphql Claude

MCP GraphQL销售服务器

一个模型上下文协议（MCP）服务器，通过GraphQL查询提供对销售数据的访问。该服务器允许像Claude这样的AI助手通过自然语言查询与Northwind风格的销售数据库进行交互。

🚀 特性

• GraphQL API 通过全面的销售数据查询
• MCP服务器 与Claude Desktop和其他MCP客户端兼容
• 丰富的分析 包括客户摘要、产品分析和订单统计
• 基于日期的筛选 用于时间范围查询
• FastMCP 集成，便于工具开发

📊 可用数据和查询

核心实体

• 订单 -完整的订单信息，包括详细信息、发货和行项目
• 客户 -客户信息和购买历史
• 产品 -包含定价和销售数据的产品目录
• 员工 -与订单关联的员工信息

查询功能

• 按ID获取所有订单或特定订单
• 按客户（姓名或ID）筛选订单
• 计算客户支出总额和订单数量
• 为客户和产品生成销售摘要
• 日期范围过滤和分析
• 按数量或收入排名的顶级产品

🛠 安装和设置

先决条件

• Python 3.8或更高版本
• 紫外线 包管理器
• Claude Desktop（用于MCP集成）

1.克隆存储库

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

2.设置Python环境

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

3.准备数据

确保您的销售数据文件位于 sales/data.json。数据应遵循Northwind数据库结构，订单包含：

{
  "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.环境配置

创建一个 .env 文件（可选）：

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

🚦 运行应用程序

选项1：启动两台服务器

终端1-GraphQL服务器：

python graphql_client/client.py

终端2-MCP服务器：

python main.py

选项2：使用紫外线

# GraphQL Server
uv run graphql_client/client.py

# MCP Server  
uv run main.py

🔌 Claude桌面集成

1.找到Claude桌面配置

macOS：

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

窗户：

%APPDATA%\Claude\claude_desktop_config.json

2.添加MCP服务器配置

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

重要提示： 替换 /full/path/to/mcp-graphql-sales-server 使用项目目录的实际绝对路径。

3.重新启动克劳德桌面

完全退出并重新启动Claude Desktop以加载新配置。

💬 使用示例

一旦与Claude Desktop集成，您可以提出以下问题：

"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?"

📊 现场演示-交互式销售报告

看看这个 交互式可视化 按销售额和订单数显示前10名客户： 十大客户销售报告

此报告演示了使用此具有Claude数据分析功能的MCP服务器可以生成的丰富分析和可视化。

🔍 GraphQL游乐场

访问GraphQL游乐场：http://127.0.0.1:5001/graphql

查询示例

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

📁 项目结构

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

🛠 可用的MCP工具

服务器为AI交互提供了以下工具：

• graphql_query -执行原始GraphQL查询
• test_connection -测试GraphQL端点连接
• get_all_orders -检索所有订单及其完整详细信息
• get_order_by_id -按ID获取特定订单
• get_orders_by_customer_name -按名称获取客户订单
• get_orders_by_customer_id -按ID获取客户订单
• get_total_spent_by_customer -计算客户总支出
• orders_after_date -在特定日期后过滤订单
• orders_between_dates -筛选日期范围内的订单
• get_order_summary -获取全面的订单统计数据

🐛 故障排除

常见问题

1. 400个错误请求：确保GraphQL服务器在端口5001上运行
2. MCP工具未显示：检查Claude Desktop配置路径并重新启动应用程序
3. 数据文件错误：验证 sales/data.json 存在并且格式正确
4. 权限错误：确保所有文件可读且路径正确

除错记录

在以下位置查看日志： /tmp/mcp_sales_server.log

直接测试GraphQL

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

📄 需求

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

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📝 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 内置于 FastMCP 便于MCP服务器开发
• 用途 石墨烯 用于GraphQL模式生成
• 受Northwind数据库示例数据结构的启发

______________________________________________________________________

需要帮助？ 在GitHub上打开一个问题或查看上面的故障排除部分。