Citus MCP

Citus MCP是一个基于Model Context Protocol的AI助手服务器，专为管理Citus分布式PostgreSQL集群设计，提供集群检查、监控、智能建议和安全操作功能。

数据库开发者工具 #分布式数据库 #AI助手 #PostgreSQL #集群管理 .Go

评分 : 2.5分

下载量 : 0

更新时间 : 2026-03-12

打开站点

什么是Citus MCP Server?

Citus MCP Server是一个连接AI助手（如GitHub Copilot）与Citus分布式PostgreSQL集群的桥梁。它允许您通过自然语言对话来： • 安全地查看集群状态和表结构 • 监控查询性能和锁等待 • 分析数据分布是否均衡 • 获取配置优化建议 • 在安全控制下执行管理操作它就像一个智能的集群管理员，您可以通过聊天的方式与它交流，获取专业级的数据库运维建议。

如何使用Citus MCP Server?

使用Citus MCP Server非常简单，只需三个步骤： 1. **安装配置**：下载或构建服务器，配置数据库连接 2. **集成到Copilot**：在VS Code或GitHub Copilot CLI中添加服务器配置 3. **开始对话**：在Copilot聊天中@citus-mcp提问，如“@citus-mcp 显示集群状态” 您不需要记住复杂的SQL命令，只需用自然语言描述您想了解或解决的问题。

适用场景

Citus MCP Server特别适合以下场景： • **日常运维**：快速检查集群健康状态，无需登录数据库 • **故障排查**：当查询变慢时，快速分析锁等待、热点分片等问题 • **容量规划**：了解数据分布是否均衡，是否需要扩容 • **新手学习**：通过问答方式了解Citus集群的工作原理 • **团队协作**：为团队成员提供统一的集群查询界面

主要功能

集群检查

安全地查看集群中的所有组件：节点、分布式表、分片、索引等。所有检查操作都是只读的，不会影响生产环境。

实时监控

实时监控集群活动：正在运行的查询、锁等待情况、后台任务进度等。帮助您快速发现性能瓶颈。

智能分析

自动分析数据分布是否均衡、识别热点分片、评估配置合理性。提供可操作的优化建议。

专家顾问

内置SRE专家系统，提供集群健康检查、配置优化、扩容建议等专业指导。

安全操作

危险操作（如重新平衡数据）需要明确的批准令牌，防止意外操作。支持只读模式确保安全。

无缝集成

直接集成到VS Code和GitHub Copilot CLI中，无需切换工具。支持多种传输方式（stdio/SSE/HTTP）。

优势

🤖 **AI驱动**：用自然语言与数据库交互，无需记忆复杂命令

🛡️ **安全第一**：默认只读模式，危险操作需要明确批准

📊 **全面洞察**：提供集群级视图，而不仅仅是单个数据库

⚡ **快速诊断**：一键式健康检查和性能分析

🔧 **开箱即用**：预置最佳实践检查和优化建议

🌐 **多方式访问**：支持VS Code、CLI和HTTP API多种接入方式

局限性

📚 **需要Citus知识**：虽然简化了操作，但理解Citus基本概念仍有帮助

🔗 **依赖Copilot**：主要设计用于GitHub Copilot生态系统

⚙️ **配置要求**：需要正确配置数据库连接和网络访问

📈 **监控范围**：专注于Citus特定功能，不是完整的APM解决方案

🔄 **实时性**：监控数据有轻微延迟（可配置缓存时间）

如何使用

安装服务器

下载预编译版本或从源代码构建。确保系统已安装Go 1.23+和Citus集群访问权限。

配置连接

创建配置文件或设置环境变量，指定Citus协调器节点的连接信息。

集成到Copilot

在VS Code工作区创建mcp.json文件，配置服务器路径和连接参数。

开始使用

重启VS Code，打开Copilot聊天，使用@citus-mcp前缀提问。

使用案例

日常健康检查

每天早上检查集群健康状态，确保一切正常运行

性能问题排查

当用户报告查询变慢时，快速定位瓶颈

容量规划

计划扩容前评估当前数据分布和节点负载

配置优化

定期检查并优化集群配置参数

常见问题

Citus MCP Server安全吗？会修改我的数据吗？

我需要多少数据库权限才能使用？

会影响数据库性能吗？

支持哪些Citus版本？

可以在生产环境使用吗？

如何获取帮助或报告问题？

🚀 Citus MCP 服务器

一款由人工智能驱动的 MCP 服务器，用于管理 Citus 分布式 PostgreSQL 集群

本项目借助先进的人工智能技术，为 Citus 分布式 PostgreSQL 集群提供高效、智能的管理方案，能显著提升集群的管理效率和稳定性。

快速开始 • 主要特性 • 安装指南 • 配置说明 • 工具参考 • 使用示例

🚀 快速开始

前提条件

Go 1.23 及以上版本（用于从源代码构建）
可访问协调器的 Citus 12.x - 14.x 集群
支持 MCP 的 GitHub Copilot（VS Code 或 CLI）

1. 构建服务器

git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp
make build
# 二进制文件将生成在 ./bin/citus-mcp

或者直接使用 Go 进行构建：

go build -o bin/citus-mcp ./cmd/citus-mcp

2. 配置连接

在 ~/.config/citus-mcp/config.yaml 中创建配置文件：

# 最低要求的配置
coordinator_dsn: postgres://username:password@localhost:5432/mydb?sslmode=disable

或者设置环境变量：

export CITUS_MCP_COORDINATOR_DSN="postgres://username:password@localhost:5432/mydb?sslmode=disable"

3. 设置 VS Code

在工作区创建 .vscode/mcp.json（或在项目根目录创建 mcp.json）：

{
  "mcpServers": {
    "citus-mcp": {
      "command": "/path/to/citus-mcp/bin/citus-mcp",
      "args": [],
      "env": {
        "CITUS_MCP_COORDINATOR_DSN": "postgres://username:password@localhost:5432/mydb?sslmode=disable"
      }
    }
  }
}

4. 测试连接

在 VS Code Copilot 聊天中输入：

@citus-mcp ping

若看到 "pong" 响应，则表明连接正常。

✨ 主要特性

🔍 集群检查（只读）

工具	描述
`citus_cluster_summary`	协调器、工作节点、表数量和配置健康状况的概述
`list_nodes`	列出所有协调器和工作节点
`list_distributed_tables`	列出分布式表和引用表
`citus_list_distributed_tables`	带过滤器的分布式表分页列表
`citus_list_reference_tables`	引用表的分页列表
`list_shards`	列出分片及其位置和大小
`citus_table_inspector`	深入查看表元数据、索引和统计信息
`citus_colocation_inspector`	分析 coloc 组和共置表

📊 监控与分析

工具	描述
`citus_activity`	集群范围内的活动查询和连接
`citus_lock_inspector`	查看锁等待和阻塞查询
`citus_job_inspector`	后台作业进度（重新平衡、复制）
`citus_shard_heatmap`	热点分片和节点分布
`citus_shard_skew_report`	每个节点的数据倾斜分析
`citus_explain_query`	解释分布式查询

🤖 智能顾问

工具	描述
`citus_advisor`	提供可操作建议的 SRE 和性能顾问
`citus_config_advisor`	全面的 Citus 和 PostgreSQL 配置分析
`citus_snapshot_source_advisor`	为基于快照的扩展推荐源节点
`citus_validate_rebalance_prereqs`	检查表是否准备好进行重新平衡
`citus_metadata_health`	检测元数据损坏和不一致，并提供修复建议
`citus_node_prepare_advisor`	为添加新节点进行预检查和准备脚本

⚡ 执行操作（需要批准）

工具	描述
`citus_rebalance_plan`	预览重新平衡操作
`citus_rebalance_execute`	启动集群重新平衡
`citus_rebalance_status`	监控重新平衡进度
`citus_move_shard_plan`	预览分片移动
`citus_move_shard_execute`	将分片移动到不同节点
`citus_request_approval_token`	请求限时批准令牌

📦 安装指南

选项 1：从源代码构建

# 克隆仓库
git clone https://github.com/citusdata/citus-mcp.git
cd citus-mcp

# 使用 Make 进行构建
make build

# 或者直接使用 Go 构建
go build -o bin/citus-mcp ./cmd/citus-mcp

# （可选）安装到系统路径
sudo cp bin/citus-mcp /usr/local/bin/

选项 2：使用 Go 安装

go install github.com/citusdata/citus-mcp/cmd/citus-mcp@latest

验证安装

citus-mcp --help

⚙️ 配置说明

连接字符串（DSN）

最重要的配置是指向 Citus 协调器的 PostgreSQL 连接字符串：

postgres://[用户]:[密码]@[主机]:[端口]/[数据库]?sslmode=[模式]

示例：

# 本地开发（无 SSL）
postgres://postgres:secret@localhost:5432/mydb?sslmode=disable

# 生产环境使用 SSL
postgres://admin:secret@citus-coord.example.com:5432/production?sslmode=require

# 指定特定模式
postgres://user:pass@host:5432/db?sslmode=require&search_path=myschema

配置方法

配置可以通过以下方式提供（按优先级顺序）：

命令行标志
环境变量
配置文件

方法 1：环境变量

# 必需
export CITUS_MCP_COORDINATOR_DSN="postgres://user:pass@localhost:5432/mydb?sslmode=disable"

# 可选
export CITUS_MCP_MODE="read_only"           # 只读（默认）或管理员模式
export CITUS_MCP_ALLOW_EXECUTE="false"      # 启用执行操作
export CITUS_MCP_APPROVAL_SECRET="secret"   # 如果 allow_execute=true 则必需
export CITUS_MCP_LOG_LEVEL="info"           # 调试、信息、警告、错误

方法 2：配置文件

创建 ~/.config/citus-mcp/config.yaml：

# ===========================================
# Citus MCP 服务器配置
# ===========================================

# 数据库连接（必需）
# -----------------------------
coordinator_dsn: postgres://user:password@localhost:5432/mydb?sslmode=disable

# 可选：覆盖 DSN 中的凭据
# coordinator_user: myuser
# coordinator_password: mypassword

# 可选：直接连接工作节点（逗号分隔）
# worker_dsns: postgres://user:pass@worker1:5432/db,postgres://user:pass@worker2:5432/db

# 服务器模式
# -----------
# read_only: 仅提供检查工具（默认，最安全）
# admin: 提供所有工具，包括执行操作
mode: read_only

# 执行操作（仅当 mode=admin 时）
# ---------------------------------------
allow_execute: false
# approval_secret: your-secret-key  # 如果 allow_execute=true 则必需

# 性能设置
# --------------------
cache_ttl_seconds: 5          # 元数据查询的缓存持续时间
enable_caching: true          # 设置为 false 可禁用缓存
max_rows: 200                 # 每个查询返回的最大行数
max_text_bytes: 200000        # 响应中的最大文本大小

# 超时设置
# --------
connect_timeout_seconds: 10   # 连接超时时间
statement_timeout_ms: 30000   # 查询超时时间（30 秒）

# 日志记录
# -------
log_level: info               # 调试、信息、警告、错误

# 传输方式（新增）
# ---------------
# stdio: 标准输入/输出（默认，用于 VS Code/CLI 集成）
# sse: 通过 HTTP 的服务器发送事件（用于远程/网络访问）
# streamable: 可流式传输的 HTTP 传输（用于远程/网络访问）
transport: stdio

# HTTP 设置（仅当传输方式为 sse 或 streamable 时使用）
# http_addr: 127.0.0.1        # 监听地址（使用 0.0.0.0 表示所有接口）
# http_port: 8080             # 监听端口
# http_path: /mcp             # 端点路径
# sse_keepalive_seconds: 30   # SSE 保持活动间隔

方法 3：命令行标志

# 使用标志（注意：标志名使用下划线）
bin/citus-mcp --coordinator_dsn "postgres://..." --mode read_only

# 使用位置参数指定 DSN
bin/citus-mcp "postgres://user:pass@localhost:5432/mydb?sslmode=disable"

# 指定配置文件
bin/citus-mcp --config /path/to/config.yaml

# 使用 SSE 传输方式启动
bin/citus-mcp --transport sse --http_port 8080 --coordinator_dsn "postgres://..."

配置文件位置

服务器按以下顺序搜索配置文件：

--config / -c 标志
CITUS_MCP_CONFIG 环境变量
$XDG_CONFIG_HOME/citus-mcp/config.yaml
~/.config/citus-mcp/config.yaml
./citus-mcp.yaml（当前目录）

支持的格式：YAML、JSON、TOML

🌐 传输选项

Citus MCP 支持三种传输模式，以适应不同的部署场景：

1. 标准输入/输出传输（默认）

标准输入/输出传输方式，服务器通过标准输入/输出进行通信。这是默认模式，用于与 VS Code 和 GitHub Copilot CLI 直接集成。

# 默认 - 标准输入/输出传输
bin/citus-mcp --coordinator_dsn "postgres://..."

# 显式指定
bin/citus-mcp --transport stdio --coordinator_dsn "postgres://..."

使用场景：

VS Code Copilot 聊天集成
GitHub Copilot CLI
本地开发

2. SSE 传输（服务器发送事件）

基于 HTTP 的传输方式，使用服务器发送事件。服务器作为 HTTP 守护进程运行，客户端可以远程连接。

# 使用 SSE 在 HTTP 上启动服务器
bin/citus-mcp --transport sse --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."

# 或者通过环境变量设置
export CITUS_MCP_TRANSPORT=sse
export CITUS_MCP_HTTP_ADDR=0.0.0.0
export CITUS_MCP_HTTP_PORT=8080
export CITUS_MCP_COORDINATOR_DSN="postgres://..."
bin/citus-mcp

端点：

GET /mcp - 建立 SSE 连接
POST /mcp/session/{id} - 向会话发送消息
GET /health - 健康检查

使用场景：

远程 MCP 服务器部署
Docker/Kubernetes 部署
多客户端共享服务器
网络可访问的 MCP 服务

3. 可流式传输的 HTTP 传输

具有流式支持的现代 HTTP 传输方式，推荐用于新的部署。

# 使用可流式传输的 HTTP 传输启动服务器
bin/citus-mcp --transport streamable --http_addr 0.0.0.0 --http_port 8080 --coordinator_dsn "postgres://..."

端点：

POST /mcp - 处理 MCP 请求并提供流式响应
GET /health - 健康检查

使用场景：

与 SSE 相同，但具有更好的流式支持
SSE 不理想的环境

Docker 部署示例

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY . .
RUN go build -o citus-mcp ./cmd/citus-mcp

FROM alpine:latest
COPY --from=builder /app/citus-mcp /usr/local/bin/
EXPOSE 8080
CMD ["citus-mcp", "--transport", "sse", "--http-addr", "0.0.0.0", "--http-port", "8080"]

# docker-compose.yml
version: '3.8'
services:
  citus-mcp:
    build: .
    ports:
      - "8080:8080"
    environment:
      CITUS_MCP_TRANSPORT: sse
      CITUS_MCP_HTTP_ADDR: 0.0.0.0
      CITUS_MCP_HTTP_PORT: 8080
      CITUS_MCP_COORDINATOR_DSN: postgres://user:pass@citus-coordinator:5432/mydb?sslmode=disable

连接到远程服务器

对于 SSE/可流式传输的传输方式，配置 MCP 客户端通过 HTTP 连接：

{
  "mcpServers": {
    "citus-mcp": {
      "type": "sse",
      "url": "http://citus-mcp-server:8080/mcp"
    }
  }
}

🔌 与 GitHub Copilot 集成设置

VS Code 设置

安装先决条件
- 安装带有 GitHub Copilot 扩展的 VS Code
- 在 Copilot 设置中启用 MCP 支持

创建 MCP 配置 在工作区创建 .vscode/mcp.json：

{
  "mcpServers": {
    "citus-mcp": {
      "command": "/absolute/path/to/bin/citus-mcp",
      "args": [],
      "env": {
        "CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
      }
    }
  }
}

或者用于开发（使用 go run）：

{
  "mcpServers": {
    "citus-mcp": {
      "command": "go",
      "args": ["run", "./cmd/citus-mcp"],
      "cwd": "/path/to/citus-mcp",
      "env": {
        "CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
      }
    }
  }
}

重新加载 VS Code 并打开 Copilot 聊天
验证连接
```
@citus-mcp ping
```

GitHub Copilot CLI 设置

创建全局 MCP 配置 创建 ~/.config/github-copilot/mcp.json：

{
  "mcpServers": {
    "citus-mcp": {
      "command": "/usr/local/bin/citus-mcp",
      "args": [],
      "env": {
        "CITUS_MCP_COORDINATOR_DSN": "postgres://user:pass@localhost:5432/mydb?sslmode=disable"
      }
    }
  }
}

验证设置

copilot mcp list
copilot mcp test citus-mcp

在 CLI 中使用

copilot -p "Show me the cluster summary"

💻 使用示例

基础集群检查

@citus-mcp Show me the cluster summary

@citus-mcp List all distributed tables

@citus-mcp Inspect the public.users table including shards and indexes

监控

@citus-mcp Show current cluster activity

@citus-mcp Are there any lock waits in the cluster?

@citus-mcp Show background job progress

分析

@citus-mcp Analyze shard skew for the orders table

@citus-mcp Show me the shard heatmap grouped by node

@citus-mcp Explain this query: SELECT * FROM orders WHERE customer_id = 123

顾问

@citus-mcp Run the advisor with focus on skew

@citus-mcp Check operational health (long queries, locks, jobs)

@citus-mcp Suggest the best source node for snapshot-based scaling

@citus-mcp Check metadata health with deep validation across nodes

配置分析

@citus-mcp Analyze cluster configuration and recommend improvements

@citus-mcp Run config advisor with focus on memory settings

共置分析

@citus-mcp Show all colocation groups

@citus-mcp Which tables are colocated with the orders table?

节点添加

@citus-mcp Run pre-flight checks for adding node at postgres://user:pass@newworker:5432/db

📚 工具参考

检查工具

工具	参数	描述
`ping`	`message?`	健康检查
`server_info`	—	服务器元数据和模式
`list_nodes`	`limit?`, `offset?`	协调器和工作节点
`list_distributed_tables`	`limit?`, `offset?`	所有分布式表
`list_shards`	`limit?`, `offset?`	带位置信息的分片
`citus_cluster_summary`	`include_workers?`, `include_gucs?`, `include_config?`	包含配置健康状况的完整集群概述
`citus_list_distributed_tables`	`schema?`, `table_type?`, `limit?`, `cursor?`	分页表列表
`citus_list_reference_tables`	`schema?`, `limit?`, `cursor?`	分页引用表列表
`citus_table_inspector`	`table` (必需), `include_shards?`, `include_indexes?`	深入查看表
`citus_colocation_inspector`	`colocation_id?`, `limit?`	共置组

监控工具

工具	参数	描述
`citus_activity`	`limit?`, `include_idle?`, `min_duration_secs?`	活动查询
`citus_lock_inspector`	`include_locks?`, `limit?`	锁等待
`citus_job_inspector`	`state?`, `include_tasks?`, `limit?`	后台作业
`citus_shard_heatmap`	`table?`, `limit?`, `metric?`, `group_by?`	热点分片
`citus_shard_skew_report`	`table?`, `metric?`, `include_top_shards?`	倾斜分析
`citus_explain_query`	`sql` (必需), `analyze?`, `verbose?`, `costs?`	解释查询

顾问工具

工具	参数	描述
`citus_advisor`	`focus?` (`skew`/`ops`), `max_tables?`, `include_next_steps?`, `include_sql_fixes?`	SRE 顾问
`citus_config_advisor`	`include_all_gucs?`, `category?`, `severity_filter?`, `total_ram_gb?`	配置分析
`citus_snapshot_source_advisor`	`strategy?`, `max_candidates?`, `include_simulation?`	节点添加建议
`citus_validate_rebalance_prereqs`	`table` (必需)	重新平衡准备情况
`citus_metadata_health`	`check_level?` (`basic`/`thorough`/`deep`), `include_fixes?`	元数据一致性检查
`citus_node_prepare_advisor`	`host` (必需), `port?`, `database?`, `generate_script?`	预检查和准备脚本

执行工具（需要批准）

工具	参数	描述
`citus_rebalance_plan`	`table?`, `threshold?`, `max_shard_moves?`, `drain_only?`	预览重新平衡
`citus_rebalance_execute`	`approval_token` (必需), `table?`, `threshold?`	启动重新平衡
`citus_rebalance_status`	`verbose?`, `limit?`, `cursor?`	重新平衡进度
`citus_move_shard_plan`	`shard_id`, `source_host`, `source_port`, `target_host`, `target_port`, `colocated?`	预览分片移动
`citus_move_shard_execute`	`approval_token` (必需), `shard_id`, `source_`, `target_`, `colocated?`, `drop_method?`	执行分片移动
`citus_request_approval_token`	`action` (必需), `ttl_seconds?`	获取批准令牌
`rebalance_table_plan`	`table` (必需)	旧版：计划表重新平衡
`rebalance_table_execute`	`table` (必需), `approval_token` (必需)	旧版：执行表重新平衡

📋 内置提示

在 Copilot 聊天中使用这些提示以获得引导式工作流程：

提示	描述
`/citus.health_check`	集群健康检查清单
`/citus.rebalance_workflow`	分步重新平衡指南
`/citus.skew_investigation`	倾斜调查手册
`/citus.ops_triage`	操作分诊工作流程

🔐 安全说明

只读模式（默认）

默认情况下，citus-mcp 以 只读模式 运行。这意味着：

✅ 所有检查和监控工具均可正常使用
✅ 顾问提供建议
❌ 执行操作被禁用
❌ 无法修改数据

管理员模式与批准令牌

要启用执行操作：

在配置中设置管理员模式：

mode: admin
allow_execute: true
approval_secret: your-secret-key-here

执行前请求批准令牌：

@citus-mcp Request approval token for rebalance

在执行命令中使用令牌：

@citus-mcp Execute rebalance with token: <token>

令牌具有时间限制且特定于操作（使用 HMAC 签名）。

🔧 故障排除

连接问题

错误：connection refused

验证协调器主机和端口是否正确
检查 PostgreSQL 是否正在运行并接受连接
确保防火墙规则允许连接

错误：authentication failed

验证 DSN 中的用户名和密码
检查用户是否对数据库具有权限
对于 SSL 问题，本地测试时可尝试 sslmode=disable

MCP 问题

Copilot 无法识别 citus-mcp

确保 mcp.json 位于正确位置
检查命令路径是否为绝对路径
修改配置后重新加载 VS Code

工具返回错误

查看日志：CITUS_MCP_LOG_LEVEL=debug bin/citus-mcp
验证 Citus 扩展是否已安装：SELECT * FROM pg_extension WHERE extname = 'citus'

测试连接

# 直接测试
CITUS_MCP_COORDINATOR_DSN="postgres://..." bin/citus-mcp

# 然后通过标准输入发送 ping 请求
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | bin/citus-mcp

🛠️ 开发说明

运行测试

# 单元测试
make test

# 详细输出
go test -v ./...

# 集成测试（需要 Docker）
make docker-up
make integration
make docker-down

代码检查

make lint

项目结构

citus-mcp/
├── cmd/citus-mcp/       # 主入口点
├── internal/
│   ├── mcpserver/       # MCP 服务器实现
│   │   ├── tools/       # 工具实现（30 多个工具）
│   │   ├── prompts/     # 提示模板
│   │   └── resources/   # 静态资源
│   ├── db/              # 数据库层和工作节点管理
│   ├── citus/           # Citus 特定逻辑和查询
│   │   ├── advisor/     # 顾问实现
│   │   └── guc/         # GUC（配置）分析
│   ├── cache/           # 查询结果缓存
│   ├── config/          # 配置管理
│   ├── errors/          # 错误类型和代码
│   ├── fanout