使用说明

项目简介

QueryPie MCP Server 是一个基于 Model Context Protocol (MCP) 构建的应用后端，专为 QueryPie 数据平台设计。它充当 LLM 客户端与 QueryPie 平台之间的桥梁，使得 LLM 应用能够安全、便捷地访问 QueryPie 平台上的数据资源和功能。通过标准化的 MCP 协议，QueryPie MCP Server 简化了 LLM 应用与后端数据服务的集成过程，提升了开发效率和应用性能。

主要功能点

资源 (Resources) 访问: 通过 QueryPie 平台提供的 API 接口，LLM 应用可以安全地访问和查询数据库、数据表等资源。
工具 (Tools) 集成: 将 QueryPie 平台的功能 (例如查询执行、数据分析等) 封装为 MCP 工具，供 LLM 客户端调用，扩展 LLM 的能力边界。
Prompt 模板 (Prompts): 支持自定义 Prompt 模板，允许开发者根据具体应用场景定制与 LLM 的交互模式，优化用户体验。
多种传输协议: 支持 Stdio 和 SSE (Server-Sent Events) 两种传输协议，满足不同应用场景的需求。
会话管理: 服务器端负责管理会话，确保 LLM 客户端请求的上下文关联性。
能力声明: 通过 MCP 协议向客户端声明服务器所提供的资源和工具能力。
OpenAPI 支持: 基于 QueryPie 平台的 OpenAPI 规范自动生成 MCP 工具，简化工具集成过程。
缓存机制: 支持 OpenAPI 规范缓存，提升服务器启动速度和性能。

安装步骤

准备 QueryPie API Key 和 URL:
- 登录 QueryPie Web 控制台，在 <kbd>General</kbd> > <kbd>System</kbd> > <kbd>API Token</kbd> 页面获取 API Key。
- 记录您的 QueryPie 平台 URL (例如 'https://your_querypie_url')。

选择安装方式: 您可以选择 Docker 或 Linux/macOS 方式安装。

Docker 安装 (推荐)

确保您已安装 Docker。

打开终端，根据您需要的传输协议执行以下命令：

Stdio 示例:

export QUERYPIE_API_KEY=your_token  # 替换为您的 QueryPie API Key
export QUERYPIE_URL=https://your_querypie_url # 替换为您的 QueryPie URL

docker run --rm \
    -e "QUERYPIE_API_KEY=${QUERYPIE_API_KEY}" \
    ghcr.io/querypie/querypie-mcp-server "${QUERYPIE_URL}"

SSE 示例:

export QUERYPIE_API_KEY=your_token  # 替换为您的 QueryPie API Key
export QUERYPIE_URL=https://your_querypie_url # 替换为您的 QueryPie URL

docker run --rm \
    -e "QUERYPIE_API_KEY=${QUERYPIE_API_KEY}" \
    ghcr.io/querypie/querypie-mcp-server "${QUERYPIE_URL}" \
    --transport sse \
    --port 8000

Linux/macOS 安装

打开终端，执行以下命令安装 'querypie-mcp-server' 二进制文件到 '~/.local/bin':

curl -L https://github.com/querypie/querypie-mcp-server/releases/latest/download/install.sh | sh

安装完成后，您可以选择 Stdio 或 SSE 方式启动服务器。

Stdio 示例:

export QUERYPIE_API_KEY=your_token # 替换为您的 QueryPie API Key
querypie-mcp-server https://your_querypie_url # 替换为您的 QueryPie URL

SSE 示例:

export QUERYPIE_API_KEY=your_token # 替换为您的 QueryPie API Key
querypie-mcp-server https://your_querypie_url # 替换为您的 QueryPie URL \
    --transport sse \
    --port 8000

服务器配置

MCP 客户端 (例如 Claude Desktop, Cursor) 需要配置 MCP 服务器的启动命令及其参数才能连接。以下是针对 Claude Desktop 和 Cursor 的配置示例：

Claude Desktop 配置 ( 'claude_desktop_config.json' )

{
    "mcpServers": {
        "querypie": {
            "command": "docker",
            "args": [
                "run",
                "-e",
                "QUERYPIE_API_KEY=${QUERYPIE_API_KEY}",
                "-it",
                "ghcr.io/querypie/querypie-mcp-server",
                "https://your_querypie_url"
            ],
            "env": {
                "QUERYPIE_API_KEY": "your_token"
            }
        }
    }
}

'server name': 'querypie' (可自定义，用于在 Claude 中标识服务器)
'command': 'docker' (服务器启动命令，这里使用 Docker 运行)
'args': '["run", "-e", "QUERYPIE_API_KEY=${QUERYPIE_API_KEY}", "-it", "ghcr.io/querypie/querypie-mcp-server", "https://your_querypie_url"]' (命令参数，包括 Docker 运行参数、环境变量设置、镜像名称和 QueryPie URL)
'env': '{"QUERYPIE_API_KEY": "your_token"}' (环境变量配置，可选，这里通过 args 传递环境变量)

Cursor 配置 ( '~/cursor/mcp.json' )

{
  "mcpServers": {
    "querypie": {
      "command": "docker",
      "type": "stdio",
      "args": [
        "run",
        "-e",
        "QUERYPIE_API_KEY=${QUERYPIE_API_KEY}",
        "-it",
        "ghcr.io/querypie/querypie-mcp-server",
        "https://your_querypie_url"
      ],
      "env": {
        "QUERYPIE_API_KEY": "your_token"
      }
    }
  }
}

'server name': 'querypie' (可自定义)
'command': 'docker' (服务器启动命令)
'type': 'stdio' (传输协议类型，这里使用 Stdio)
'args': '["run", "-e", "QUERYPIE_API_KEY=${QUERYPIE_API_KEY}", "-it", "ghcr.io/querypie/querypie-mcp-server", "https://your_querypie_url"]' (命令参数，与 Claude 示例类似)
'env': '{"QUERYPIE_API_KEY": "your_token"}' (环境变量配置)

注意: 请将 'your_token' 替换为您的实际 QueryPie API Key，'https://your_querypie_url' 替换为您的实际 QueryPie 平台 URL。

基本使用方法

启动 QueryPie MCP Server: 根据您的安装方式和配置选择 Stdio 或 SSE 方式启动服务器。确保服务器成功运行并监听指定端口 (如果使用 SSE)。
配置 MCP 客户端: 在您的 MCP 客户端 (例如 Claude Desktop, Cursor) 中，根据上述配置示例，添加 QueryPie MCP Server 的配置信息。
连接并使用: 在 MCP 客户端中选择配置的 QueryPie MCP Server，客户端将自动连接到服务器并获取其提供的资源和工具能力。您可以通过客户端界面或命令调用 QueryPie 平台提供的功能。

QueryPie MCP Server