CloudQuery MCP Server 使用指南

本 MCP Server 连接 CloudQuery 平台，提供五个工具，让 AI 能够探索数据库结构并执行 SQL 查询。

安装

npm install -g cq-mcp-server

运行模式

stdio 模式（Claude Desktop / OpenCode）

# 直接运行，默认 stdio
CQ_BASE_URL=http://10.10.2.73 CQ_USERNAME=xxxxx CQ_PASSWORD=xxxx cq-mcp-server

s

HTTP 模式（Dify 接入）

Dify 只支持 HTTP 传输，通过环境变量切换：

MCP_TRANSPORT=http MCP_PORT=8080 cq-mcp-server

启动后 MCP 端点为：http://<服务器IP>:8080/mcp

Dify 添加步骤：

1. Dify → Tools → MCP → Add MCP Server (HTTP)
2. Server URL 填：http://<服务器IP>:8080/mcp
3. 确认后 Dify 自动发现 connect / list_databases / list_tables / get_table_columns / execute_sql 五个工具

HTTP 模式下的认证：无需配置环境变量，在 workflow 中第一步调用 connect 工具传入地址和账密即可（适合多租户场景）。

工具调用顺序

connect（可选）→ list_databases → list_tables → get_table_columns → execute_sql

• connect：动态传入连接参数时需要先调用（如 Dify 等场景）。若已通过环境变量 CQ_BASE_URL / CQ_USERNAME / CQ_PASSWORD 配置，可跳过。
• 后续工具所需的 connection_id、connection_type、database、schema 参数，都只能从前面的工具返回结果中获取，不能凭空猜测。

工具详解

0. connect — 设置连接参数（动态场景必须首先调用）

| 参数 | 说明 | |------|------| | base_url | CloudQuery 平台地址，如 http://10.10.2.73 | | username | 登录账号 | | password | 登录密码（明文，服务端自动加密） |

返回：连接配置成功确认。调用后原 Session 失效，下次请求自动重新登录。

Dify 配置示例：在 workflow 开始节点调用 connect，将用户输入的 base_url / username / password 传入，后续工具调用无需再传。

1. list_databases — 查询数据库清单

无需任何参数。

返回所有数据库连接及其下的数据库列表，格式如下：

## 连接: pg-prod  (connection_id=1, connection_type=PostgreSQL)
  - pam
  - postgres

从返回结果中记录：

• connection_id（数字）
• connection_type（字符串，如 PostgreSQL）
• 目标数据库名称（如 pam）

2. list_tables — 查询表清单

参数（全部必填）：

| 参数 | 来源 | 说明 | |------|------|------| | connection_id | list_databases 返回 | 数字 | | connection_type | list_databases 返回 | 如 PostgreSQL | | database | list_databases 返回 | 数据库名，如 pam | | schema | 推断或尝试 | PostgreSQL 常用 public 或与库同名（如 pam）；若 public 无结果，改用库名 |

返回该 schema 下所有表名列表。

从返回结果中记录： 目标表名（如 auth_role）

3. get_table_columns — 查询表字段

参数（全部必填）：

| 参数 | 来源 | |------|------| | connection_id | list_databases | | connection_type | list_databases | | database | list_databases | | schema | list_tables 调用时使用的 schema | | table | list_tables 返回 |

返回字段名、数据类型、长度、是否可空、业务注释，格式：

字段名                    类型            长度     可空   注释
---------------------------------------------------------------------------
id                        int8            19       否     主键
role_name                 varchar         64       否     角色名称
role_code                 varchar         32       否     角色编码

从返回结果中记录： 字段名列表，用于编写 SQL。

4. execute_sql — 执行 SQL

参数：

| 参数 | 来源 | 说明 | |------|------|------| | connection_id | list_databases | | | connection_type | list_databases | 默认 PostgreSQL | | database | list_databases | | | schema | 同 list_tables | 作为 SQL 的 search_path | | sql | 根据字段结构编写 | 一次只执行一条语句 |

SELECT 返回格式：

id | role_name | role_code | description
----------------------------------------
1  | 超级管理员  | SUPER_ADMIN | 系统最高权限
2  | 普通用户   | USER        | 默认角色

共 8 行  耗时 12ms

DML 返回格式：

执行成功
影响行数: 1
耗时: 5ms

典型场景：查询角色表数据

以下是完整的 6 步流程示例：

Step 1 — 调用 list_databases（无参数）

• 获得：connection_id=1, connection_type=PostgreSQL，数据库列表包含 pam

Step 2 — 调用 list_tables

{ "connection_id": 1, "connection_type": "PostgreSQL", "database": "pam", "schema": "pam" }

• 获得：表列表，找到 auth_role

Step 3 — 调用 get_table_columns

{ "connection_id": 1, "connection_type": "PostgreSQL", "database": "pam", "schema": "pam", "table": "auth_role" }

• 获得：字段列表 id, role_name, role_code, description, ...

Step 4 — 根据字段编写 SQL：

SELECT id, role_name, role_code, description FROM pam.auth_role LIMIT 20

Step 5 — 调用 execute_sql

{
  "connection_id": 1,
  "connection_type": "PostgreSQL",
  "database": "pam",
  "schema": "pam",
  "sql": "SELECT id, role_name, role_code, description FROM pam.auth_role LIMIT 20"
}

• 获得：查询结果

注意事项

1. schema 选择：PostgreSQL 数据库的 schema 名通常与数据库同名（如数据库 pam 对应 schema pam），而不是 public。若 public 无结果，改用数据库名作为 schema。

2. 单条执行：execute_sql 每次只能执行一条 SQL 语句，不支持批量执行。

3. 结果上限：SELECT 查询最多返回 500 行。

4. SQL 写法：建议在表名前加 schema 前缀（如 pam.auth_role），避免歧义。

5. 参数不能猜测：connection_id 和 connection_type 必须通过 list_databases 获取，不能假设固定值。