PromptQL MCP Server

连接Hasura PromptQL与AI助手如Claude，通过模型上下文协议（MCP）。

概述

该项目提供了一个桥梁，通过模型上下文协议连接Hasura的PromptQL数据代理和AI助手。通过这种集成，AI助手可以直接使用自然语言查询您的企业数据，利用PromptQL的强大功能进行数据访问、分析和可视化。

功能

• 🔍 自然语言数据查询 - 使用英文提问关于您的企业数据的问题
• 📊 表格结果支持 - 获取格式化的表格查询结果
• 🔐 安全配置 - 安全地存储和管理您的PromptQL API凭证
• 📈 数据分析 - 获取数据洞察和可视化
• 🛠️ 简单集成 - 适用于Claude Desktop和其他兼容MCP的客户端

安装

先决条件

• Python 3.10或更高版本
• 包含API密钥和DDN URL的Hasura PromptQL项目
• Claude Desktop（用于交互式使用）或其他兼容MCP的客户端

从源码安装

1. 克隆仓库：

git clone https://github.com/hasura/promptql-mcp.git
cd promptql-mcp

2. 设置虚拟环境（推荐）：

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

3. 安装包：

pip install -e .

快速开始

1. 配置您的PromptQL凭证：

python -m promptql_mcp_server setup --api-key YOUR_PROMPTQL_API_KEY --ddn-url YOUR_DDN_URL

2. 测试服务器：

python -m promptql_mcp_server

3. 在新的终端中尝试示例客户端：

python examples/simple_client.py

与Claude Desktop一起使用

1. 安装Claude Desktop
2. 打开Claude Desktop并进入设置 > 开发者
3. 点击“编辑配置”并添加以下内容：

{
  "mcpServers": {
    "promptql": {
      "command": "/full/path/to/python",
      "args": ["-m", "promptql_mcp_server"]
    }
  }
}

将/full/path/to/python替换为您Python可执行文件的实际路径。

如果您使用的是虚拟环境（推荐）：

{
  "mcpServers": {
    "promptql": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["-m", "promptql_mcp_server"]
    }
  }
}

要找到您的Python路径，请运行：

which python  # 在macOS/Linux上
where python  # 在Windows上

4. 重启Claude Desktop
5. 与Claude聊天，并使用自然语言查询您的数据

示例提示给Claude

• “我们上个季度的总销售额是多少？”
• “按收入排名的前五位客户是谁？”
• “显示过去6个月的新用户注册趋势”
• “哪些产品的利润率最高？”

可用工具和提示

工具

该服务器暴露了以下MCP工具：

• ask_question - 提出关于您数据的自然语言问题
• setup_config - 配置PromptQL API密钥和DDN URL
• check_config - 验证当前配置状态

提示

• data_analysis - 创建一个特定主题的数据分析专用提示

架构

此集成遵循客户端-服务器架构：

1. PromptQL MCP Server - 一个Python服务器，通过MCP协议公开PromptQL的功能
2. MCP客户端 - 实现MCP协议的任何客户端（例如，Claude Desktop）
3. PromptQL API - Hasura的自然语言API，用于数据访问和分析

服务器在MCP协议和PromptQL API之间进行转换，实现AI助手与您的企业数据之间的无缝集成。

故障排除

命令未找到：pip 或 python

在许多系统上，尤其是macOS，您可能需要使用python3和pip3而不是python和pip。

外部管理环境错误

现代Python安装通常会阻止全局包安装。请使用安装部分中描述的虚拟环境。

没有名为promptql_mcp_server的模块

确保您已：

1. 使用pip install -e .安装了包
2. 使用正确的Python环境（如果使用虚拟环境，请确保已激活）
3. 配置Claude Desktop以使用正确的Python可执行文件路径

Python版本问题

如果您安装了多个Python版本，请确保使用Python 3.10或更高版本：

python3.10 -m venv venv  # 指定确切版本

开发

项目结构

promptql-mcp/
├── promptql_mcp_server/     # 主包
│   ├── __init__.py
│   ├── __main__.py          # 入口点
│   ├── server.py            # MCP服务器实现
│   ├── config.py            # 配置管理
│   └── api/                 # API客户端
│       ├── __init__.py
│       └── promptql_client.py # PromptQL API客户端
├── examples/                # 示例客户端
│   └── simple_client.py     # 简单的MCP客户端
├── setup.py                 # 包配置
└── README.md                # 文档

贡献

欢迎贡献！请随意提交Pull Request。

1. 分叉仓库
2. 创建您的功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m '添加一些惊人的功能'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 打开Pull Request

许可证

本项目根据MIT许可证发布 - 查看LICENSE文件了解详情。

致谢

• Hasura 创建了PromptQL
• Anthropic 开发了模型上下文协议