AnalyticDB PostgreSQL MCP Server

AnalyticDB PostgreSQL MCP 服务

AnalyticDB PostgreSQL MCP 服务充当 AI Agent 与 AnalyticDB PostgreSQL 数据库之间的通用接口。它支持 AI Agent 与 AnalyticDB PostgreSQL 无缝通信，帮助 AI Agent 获取数据库元数据并执行 SQL 操作。

安装

你可以从源代码安装服务以进行开发，也可以从 PyPI 安装以直接使用。

选项 1：从源代码安装（用于开发）

如果你想修改或为服务贡献代码，推荐使用此方法。

# 1. Clone the repository
git clone https://github.com/aliyun/alibabacloud-adbpg-mcp-server.git
cd alibabacloud-adbpg-mcp-server

# 2. Create and activate a virtual environment using uv
uv venv .venv
source .venv/bin/activate  # On Linux/macOS
# .\.venv\Scripts\activate  # On Windows

# 3. Install the project in editable mode
uv pip install -e .

选项 2：从 PyPI 安装（用于生产环境／使用）

这是在项目中直接使用服务时最简单的安装方式。

pip install adbpg-mcp-server

运行服务

服务支持两种传输模式：用于集成 MCP 客户端的 stdio（默认）模式，以及用于直接 API 访问或调试的 http 模式。

运行服务前，请确保已设置所需的环境变量。

Stdio 模式（默认）

这是与 MCP 客户端通信的标准模式。

# Run using the default transport (stdio)
uv run adbpg-mcp-server

# Or explicitly specify the transport
uv run adbpg-mcp-server --transport stdio

Streamable-HTTP 模式

此模式会开放一个 HTTP 服务，适用于测试、调试或通过 REST API 直接集成。

# Run the server in HTTP mode on the default host and port (127.0.0.1:3000)
uv run adbpg-mcp-server --transport http

# Specify a custom host and port with authentication
uv run adbpg-mcp-server --transport http --host 0.0.0.0 --port 3000 --auth-token your-secret-token

安全性： 绑定到 0.0.0.0 或任何可通过网络访问的地址时，务必通过 --auth-token 或 MCP_AUTH_TOKEN 环境变量设置身份验证令牌。如果未设置令牌，/mcp 端点将允许未经身份验证的访问。客户端必须在所有请求中包含 Authorization: Bearer <token> 标头。

MCP 集成

要将此服务集成到上级 MCP 客户端，请将以下配置添加到客户端的配置文件中。args 数组中的参数取决于你选择的传输协议。

Stdio 传输示例

"mcpServers": {
  "adbpg-mcp-server": {
    "command": "uv",
    "args": [
      "run",
      "adbpg-mcp-server",
      "--transport",
      "stdio"
    ],
    "env": {
      "ADBPG_HOST": "host",
      "ADBPG_PORT": "port",
      "ADBPG_USER": "username",
      "ADBPG_PASSWORD": "password",
      "ADBPG_DATABASE": "database",
      "GRAPHRAG_API_KEY": "graphrag llm api key",
      "GRAPHRAG_BASE_URL": "graphrag llm base url",
      "GRAPHRAG_LLM_MODEL": "graphrag llm model name",
      "GRAPHRAG_EMBEDDING_MODEL": "graphrag embedding model name",
      "GRAPHRAG_EMBEDDING_API_KEY": "graphrag embedding api key",
      "GRAPHRAG_EMBEDDING_BASE_URL": "graphrag embedding url",
      "LLMEMORY_API_KEY": "llm memory api_key",
      "LLMEMORY_BASE_URL": "llm memory base_url",
      "LLMEMORY_LLM_MODEL": "llm memory model name",
      "LLMEMORY_EMBEDDING_MODEL": "llm memory embedding model name",
      "LLMEMORY_ENABLE_GRAPH": "enable graph engine for llm memory (Default: false)"
    }
  }
}

注意： 由于 stdio 是默认模式，你可以选择从 args 数组中省略 "--transport", "stdio"。

Streamable-HTTP 传输示例

"mcpServers": {
  "adbpg-mcp-server": {
    "command": "uv",
    "args": [
      "run",
      "adbpg-mcp-server",
      "--transport",
      "http",
      "--port",
      "3000"
    ],
    "env": {
      "ADBPG_HOST": "host",
      "ADBPG_PORT": "port",
      "ADBPG_USER": "username",
      "ADBPG_PASSWORD": "password",
      "ADBPG_DATABASE": "database",
      "MCP_AUTH_TOKEN": "your-secret-token",
      "GRAPHRAG_API_KEY": "graphrag llm api key",
      "GRAPHRAG_BASE_URL": "graphrag llm base url",
      "GRAPHRAG_LLM_MODEL": "graphrag llm model name",
      "GRAPHRAG_EMBEDDING_MODEL": "graphrag embedding model name",
      "GRAPHRAG_EMBEDDING_API_KEY": "graphrag embedding api key",
      "GRAPHRAG_EMBEDDING_BASE_URL": "graphrag embedding url",
      "LLMEMORY_API_KEY": "llm memory api_key",
      "LLMEMORY_BASE_URL": "llm memory base_url",
      "LLMEMORY_LLM_MODEL": "llm memory model name",
      "LLMEMORY_EMBEDDING_MODEL": "llm memory embedding model name",
      "LLMEMORY_ENABLE_GRAPH": "enable graph engine for llm memory (Default: false)"
    }
  }
}

工具

• execute_select_sql：在 AnalyticDB PostgreSQL 服务上执行 SELECT SQL 查询

• execute_dml_sql：在 AnalyticDB PostgreSQL 服务上执行 DML（INSERT、UPDATE、DELETE）SQL 查询

• execute_ddl_sql：在 AnalyticDB PostgreSQL 服务上执行 DDL（CREATE、ALTER、DROP）SQL 查询

• analyze_table：收集表统计信息

• explain_query：获取查询执行计划

• adbpg_graphrag_upload

  • 说明： 上传文本文件（包含文件名）及其内容到 graphrag，以生成知识图谱。
  • 参数：
    • filename（text）：要上传的文件名。
    • context（text）：文件的文本内容。

• adbpg_graphrag_query

  • 说明： 使用指定的查询字符串和模式查询 graphrag。
  • 参数：
    • query_str（text）：查询内容。
    • query_mode（text）：查询模式，可选 [bypass, naive, local, global, hybrid, mix]。如果为 null，则默认为 mix。

• adbpg_graphrag.upload_decision_tree(context text, root_node text)

  • 说明： 上传以指定 root_node 为根节点的决策树。如果 root_node 不存在，则会创建新的决策树。
  • 参数：
    • context（text）：决策树的文本表示。
    • root_node（text）：根节点的内容。

• adbpg_graphrag.append_decision_tree(context text, root_node_id text)

  • 说明： 在由 root_node_id 指定的节点处，向现有决策树追加子树。
  • 参数：
    • context（text）：子树的文本表示。
    • root_node_id（text）：要追加子树的节点 ID。

• adbpg_graphrag.delete_decision_tree(root_node_entity text)

  • 描述： 删除 root_node_entity 指定节点下的子决策树。
  • 参数：
    • root_node_entity (text)：要删除的子决策树的根节点 ID。

• adbpg_llm_memory_add

  • 描述： 添加大模型长期记忆。
  • 参数：
    • messages (json)：要上传的文件名称。
    • user_id (text)：用户 ID。
    • run_id (text)：运行 ID。
    • agent_id (text)：Agent ID。
    • metadata (json)：元数据 JSON（可选）。
    • memory_type (text)：记忆类型（可选）。
    • prompt (text)：提示词（可选）。 注意：
      必须提供 user_id、run_id 或 agent_id 中的至少一个。

• adbpg_llm_memory_get_all

  • 描述： 检索与特定用户、运行或 Agent 关联的所有记忆记录。
  • 参数：
    • user_id (text)：用户 ID（可选）。如果提供，则获取该用户的所有记忆。
    • run_id (text)：运行 ID（可选）。
    • agent_id (text)：Agent ID（可选）。如果提供，则获取该 Agent 的所有记忆。 注意：
      必须提供 user_id、run_id 或 agent_id 中的至少一个。

• adbpg_llm_memory_search

  • 描述： 检索与给定查询相关、且属于特定用户、运行或 Agent 的记忆。
  • 参数：
    • query (text)：搜索查询字符串。
    • user_id (text)：用户 ID（可选）。如果提供，则获取该用户的所有记忆。
    • run_id (text)：运行 ID（可选）。
    • agent_id (text)：Agent ID（可选）。如果提供，则获取该 Agent 的所有记忆。
    • filter (json)：JSON 格式的附加筛选条件（可选）。 注意：
      必须提供 user_id、run_id 或 agent_id 中的至少一个。

• adbpg_llm_memory_delete_all：

  • 描述： 删除与特定用户、运行或 Agent 关联的所有记忆记录。
  • 参数：
    • user_id (text)：用户 ID（可选）。如果提供，则获取该用户的所有记忆。
    • run_id (text)：运行 ID（可选）。
    • agent_id (text)：Agent ID（可选）。如果提供，则获取该 Agent 的所有记忆。 注意：
      必须提供 user_id、run_id 或 agent_id 中的至少一个。

资源

内置资源

• adbpg:///schemas：获取数据库中的所有架构

资源模板

• adbpg:///{schema}/tables：列出指定架构中的所有表
• adbpg:///{schema}/{table}/ddl：获取表 DDL
• adbpg:///{schema}/{table}/statistics：显示表统计信息

环境变量

MCP 服务需要以下环境变量才能连接到 AnalyticDB PostgreSQL 实例：

• ADBPG_HOST：数据库主机地址
• ADBPG_PORT：数据库端口
• ADBPG_USER：数据库用户名
• ADBPG_PASSWORD：数据库密码
• ADBPG_DATABASE：数据库名称

对于 HTTP 传输模式，以下可选变量可启用端点身份验证：

• MCP_AUTH_TOKEN：用于 HTTP 端点身份验证的 Bearer 令牌（也可通过 --auth-token CLI 参数设置）。强烈建议在绑定到非回环地址时设置。

MCP 服务需要以下环境变量来初始化 graphRAG 和 llm memory 服务：

• API_KEY：大模型提供商或嵌入 API 的 API 密钥
• BASE_URL：大模型或嵌入服务端点的基础 URL
• LLM_MODEL：大模型名称或标识符
• EMBEDDING_MODEL：嵌入模型名称或标识符

依赖项

• Python 3.11 或更高版本
• uv（用于环境和包管理）