用于PostgreSQL操作和监控的MCP服务器
建筑与内部(DeepWiki)
概述
MCP PostgreSQL操作 是一个用于PostgreSQL数据库操作、监控和管理的专业MCP服务器。支持PostgreSQL 12-18,通过自然语言查询提供全面的数据库分析、性能监控和智能维护建议。大多数功能独立工作,但高级查询分析功能在以下情况下得到了增强 pg_stat_statements 以及(可选) pg_stat_monitor 扩展已安装。
特性
- ✅ 零配置:与PostgreSQL 12-18配合使用,开箱即用,具有自动版本检测功能。
- ✅ 自然语言:问“显示慢速查询”或“分析表膨胀”之类的问题
- ✅ 安全生产:只读操作,RDS/Aurora兼容常规用户权限。
- ✅ 扩展增强:可选
pg_stat_statements和pg_stat_monitor用于高级查询分析。 - ✅ 全面的数据库监控:性能分析、膨胀检测和维护建议。
- ✅ 智能查询分析:查询识别速度较慢
pg_stat_statements和pg_stat_monitor整合。 - ✅ 模式和关系发现:使用详细的关系映射进行数据库结构探索。
- ✅ 真空与自动真空智能:实时维护监控和有效性分析。
- ✅ 多数据库操作:无缝的跨数据库分析和监测。
- ✅ 企业就绪:具有RDS/Aurora兼容性的安全只读操作。
- ✅ 开发者友好:简单的代码库,便于定制和工具扩展。
🔧 高性能
- 版本感知I/O统计(在PostgreSQL 16+上增强,在PG 18+上增强字节列)。
- 实时连接和锁监控。
- 后台流程和检查点分析。
- 复制状态和WAL监控。
- 数据库容量和膨胀分析。
- 等待带有描述的事件目录(PG 17+)。
- WAL汇总器监控增量备份(PG 17+)。
- 异步I/O子系统监控(PG 18+)。
- 根据后端I/O和WAL统计数据(PG 18+)。
工具使用示例
📸 更多截图示例→
⭐ 快速入门(5分钟)
注: 这
postgresql集装箱包含在docker-compose.yml仅用于快速入门测试目的。您可以通过根据需要调整环境变量来连接到自己的PostgreSQL实例。
如果你想使用自己的PostgreSQL实例而不是内置的测试容器:
- 在您的数据库中更新目标PostgreSQL连接信息
.env文件(请参见POSTGRES_HOST、POSTGRES_PORT、POSTGRESS_USER、POTGRES_PASSWORD、POSTGRES_DB)。- 在
docker-compose.yml,注释掉(禁用)postgres和postgres-init-extensions容器,以避免启动内置测试数据库。
快速入门/教程流程图
1.环境设置
备注:虽然超级用户权限提供对所有数据库和系统信息的访问,但MCP服务器也可以使用常规用户权限进行基本监控任务。
BASH``` 1 2 3 4 5git clone https://github.com/call518/MCP-PostgreSQL-Ops.git cd MCP-PostgreSQL-Ops
Check and modify .env file
cp .env.example .env vim .env
BASH```
1
2
3
4
5
6### No need to modify defaults, but if using your own PostgreSQL server, edit below:
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=15432 # External port for host access (mapped to internal 5432)
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme!@34
POSTGRES_DB=ecommerce # Default connection DB. Superusers can access all DBs.
备注:
PGDATA=/data/db为Percona PostgreSQL Docker镜像预配置,这需要此特定路径才能获得适当的写入权限。
2.启动演示容器
BASH``` 1 2 3 4 5 6# Start all containers including built-in PostgreSQL for testing docker-compose up -d
Alternative: If using your own PostgreSQL instance
Comment out postgres and postgres-init-extensions services in docker-compose.yml
Then use the custom configuration:
docker-compose -f docker-compose.custom-db.yml up -d
> **⏰ 等待环境设置**:由于容器按顺序启动,初始环境设置需要几分钟的时间:
>
>
> 1. **PostgreSQL** 容器首先从数据库初始化开始
> 2. **PostgreSQL扩展** 容器安装扩展并创建全面的测试数据(约83K条记录)
> 3. **MCP 服务器** 和 **MCPO代理** 容器在PostgreSQL准备就绪后启动
> 4. **OpenWeb用户界面** 容器最后启动,可能需要额外的时间来加载web界面
>
>
> **💡 小贴士**:跑步后等待2-3分钟 `docker-compose up -d` 在访问OpenWebUI之前,确保所有服务都已完全初始化。
**🔍 检查集装箱状态** (可选):
BASH```
1
2
3
4
5
6# Monitor container startup progress
docker-compose logs -f
# Check if all containers are running
docker-compose ps
# Verify PostgreSQL is ready
docker-compose logs postgres | grep "ready to accept connections"
3.访问OpenWebUI
-
MCP工具功能列表由提供
swagger可在MCPO API文档URL中找到。 -
例如:
http://localhost:8003/docs
4.在OpenWebUI中注册该工具
📌 备注:Web UI配置说明基于OpenWebUI v0.6.22。菜单位置和设置在较新版本中可能有所不同。
- 使用管理员帐户登录OpenWebUI
- 转到“设置”→ 顶部菜单中的“工具”。
- 进入
postgresql-ops工具地址(例如。,http://localhost:8003/postgresql-ops)连接MCP工具。 - 设置Ollama或OpenAI。
5.完成!
祝贺 您的MCP PostgreSQL操作服务器现在可以使用了。您可以开始使用自然语言查询来探索您的数据库。
🚀 尝试以下示例查询:
- “显示当前活动的连接”
- “系统中最慢的查询是什么?”
- “分析所有数据库中的表膨胀”
- “显示数据库大小信息”
- “哪些桌子需要真空维护?”
📖 下一步:
- 浏览 查询示例部分 下面是更多查询示例
- 结账 带有截图的工具使用示例 用于视觉引导
- 探索 工具兼容性矩阵 了解可用功能
(注)样品测试数据概述
这 create-test-data.sql 脚本由执行 postgres-init-extensions 容器(在docker compose.yml中定义)在首次启动时自动生成用于MCP工具测试的全面测试数据库:
| 数据库 | 用途 | 架构和表 | 规模 |
|---|---|---|---|
| 电子商务 | 电子商务系统 | 公共:类别、产品、客户、订单、订单项 | 10个类别、500个产品、100个客户、200个订单、400个订单项 |
| 分析 | 分析和报告 | 公共:page_views,sales_summary | 1000个页面浏览量,30个销售摘要 |
| 库存 | 仓库管理 | 公共:供应商、库存项目、采购订单 | 10个供应商、100个项目、50个采购订单 |
| hr_系统 | 人力资源管理 | 公共:部门、员工、工资单 | 5个部门、50名员工、150条工资单记录 |
已创建测试用户: app_readonly, app_readwrite, analytics_user, backup_user
针对测试进行了优化: 有意的表膨胀、各种索引(已使用/未使用)、时间序列数据、复杂的关系
工具兼容性矩阵
自动适应: 所有工具在支持的版本之间透明地工作,无需配置!
🟢 独立于扩展的工具(不需要扩展)
| 工具名称 | 所需扩展 | PG 12 | PG 13 | PG 14 | PG 15 | PG 16 | PG 17 | PG 18 | 使用的系统视图/表 |
|---|---|---|---|---|---|---|---|---|---|
get_server_info | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | version(), pg_extension |
get_active_connections | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_stat_activity |
get_postgresql_config | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_settings |
get_database_list | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_database |
get_table_list | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | information_schema.tables |
get_table_schema_info | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | information_schema.*, pg_indexes |
get_database_schema_info | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_namespace, pg_class, pg_proc |
get_table_relationships | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | information_schema.* (约束) |
get_user_list | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_user, pg_roles |
get_index_usage_stats | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_stat_user_indexes |
get_database_size_info | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_database_size() |
get_table_size_info | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_total_relation_size() |
get_vacuum_analyze_stats | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ 增强 | pg_stat_user_tables |
get_current_database_info | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_database, current_database() |
get_table_bloat_analysis | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_stat_user_tables |
get_database_bloat_overview | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_stat_user_tables |
get_autovacuum_status | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_stat_user_tables |
get_autovacuum_activity | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_stat_user_tables |
get_running_vacuum_operations | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_stat_activity |
get_vacuum_effectiveness_analysis | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_stat_user_tables |
get_lock_monitoring | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_locks, pg_stat_activity |
get_wal_status | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_current_wal_lsn() |
get_database_stats | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ 增强 | pg_stat_database |
get_table_io_stats | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_statio_user_tables |
get_index_io_stats | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_statio_user_indexes |
get_database_conflicts_stats | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | pg_stat_database_conflicts |
🚀 版本感知工具(自动适应)
| 工具名称 | 需要扩展 | PG 12 | PG 13 | PG 14 | PG 15 | PG 16 | PG 17 | PG 18 | 特殊功能 |
|---|---|---|---|---|---|---|---|---|---|
get_io_stats | ❌ 无 | ✅ 基础 | ✅ 基础 | ✅ 基础 | ✅ 基础 | ✅ 增强 | ✅ 增强 | ✅ 增强 | 第16+页: pg_stat_io 支持;PG18+:字节列 |
get_bgwriter_stats | ❌ 无 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ 特别 | ✅ 增强 | PG17:单独的检查指针统计信息;第18+页: num_done, slru_written |
get_replication_status | ❌ 无 | ✅ 兼容 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | 第13+页: wal_status, safe_wal_sizePG16+:增强型WAL接收机;第17+页: invalidation_reason, inactive_since |
get_all_tables_stats | ❌ 无 | ✅ 兼容 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | 第13+页: n_ins_since_vacuum 真空维护优化跟踪 |
get_user_functions_stats | ⚙️ 需要配置 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | 需要 track_functions=pl |
get_wait_events | ❌ 无 | ✅ 后退 | ✅ 后退 | ✅ 后退 | ✅ 后退 | ✅ 后退 | ✅ 本土的 | ✅ 本土的 | 第17+页: pg_wait_events 目录;PG12-16:回退到 pg_stat_activity 当前等待 |
get_wal_summarizer_status | ❌ 无 | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | ✅ | PG17+:WAL汇总器监控增量备份 |
get_async_io_status | ❌ 无 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | 第18+页: pg_aios 异步I/O子系统监控 |
get_per_backend_io_stats | ❌ 无 | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ | PG18+:按后端I/O和WAL统计 |
🟡 扩展依赖工具(需要扩展)
| 工具名称 | 所需扩展名 | PG 12 | PG 13 | PG 14 | PG 15 | PG 16 | PG 17 | PG 18 | 注释 |
|---|---|---|---|---|---|---|---|---|---|
get_pg_stat_statements_top_queries | pg_stat_statements | ✅ 兼容 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | 第12页: total_time → total_exec_time;PG13+:本地 total_exec_time;第17+页: stats_since |
get_pg_stat_monitor_recent_queries | pg_stat_monitor | ✅ 兼容 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | ✅ 增强 | 第12页: total_time → total_exec_time;PG13+:本地 total_exec_time |
🆕 版本特定功能
PostgreSQL 17
pg_wait_events视图:带有描述的本机等待事件目录(由使用get_wait_events)- WAL汇总器:监控增量备份支持(由使用
get_wal_summarizer_status) - 复制槽增强功能:
invalidation_reason和inactive_since列(由使用get_replication_status) pg_stat_statementsstats_since:跟踪上次重置统计信息的时间(由使用get_pg_stat_statements_top_queries)- 真空进度:索引真空跟踪进展视图(未来增强
get_running_vacuum_operations)
PostgreSQL 18
pg_aios视图:异步I/O子系统监控(由get_async_io_status)- 根据后端I/O统计数据:单个后端I/O和WAL统计数据(由使用
get_per_backend_io_stats) - 真空/分析时间列:
total_vacuum_time,total_autovacuum_time,total_analyze_time,total_autoanalyze_time累积计时(由get_vacuum_analyze_stats) pg_stat_io字节列:read_bytes,write_bytes,extend_bytes(使用人get_io_stats)- 平行工作者统计数据:
parallel_workers_launched,parallel_workers_to_launch(使用人get_database_stats) - 检查点增强功能:
num_done,slru_written列(由使用get_bgwriter_stats)
使用示例
Claude桌面集成
(推荐)添加到您的Claude Desktop配置文件中:
JSON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15{ “mcpServers”: { “mcp-postgresql-ops”: { “command”: “uvx”, “args”: [“—python”, “3.12”, “mcp-postgresql-ops”], “env”: { “POSTGRES_HOST”: “127.0.0.1”, “POSTGRES_PORT”: “15432”, “POSTGRES_USER”: “postgres”, “POSTGRES_PASSWORD”: “changeme!@34”, “POSTGRES_DB”: “ecommerce” } } } }
“以清晰易读的html表格格式显示所有活动连接。”
“以美人鱼图的形式显示电子商务数据库中客户表的所有关系。”
---
## 安装
### 来自PyPI(推荐)
BASH```
1
2
3
4
5
6# Install the package
pip install mcp-postgresql-ops
# Or with uv (faster)
uv add mcp-postgresql-ops
# Verify installation
mcp-postgresql-ops --help
来源
BASH``` 1 2 3 4 5 6 7 8 9# Clone the repository git clone https://github.com/call518/MCP-PostgreSQL-Ops.git cd MCP-PostgreSQL-Ops
Install with uv (recommended)
uv sync uv run mcp-postgresql-ops —help
Or with pip
pip install -e . mcp-postgresql-ops —help
---
## MCP配置
### Claude桌面配置
(可选)使用本地源运行:
JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15{
"mcpServers": {
"mcp-postgresql-ops": {
"command": "uv",
"args": ["run", "python", "-m", "mcp_postgresql_ops"],
"env": {
"POSTGRES_HOST": "127.0.0.1",
"POSTGRES_PORT": "15432",
"POSTGRES_USER": "postgres",
"POSTGRES_PASSWORD": "changeme!@34",
"POSTGRES_DB": "ecommerce"
}
}
}
}
以标准模式运行MCP服务器
/w Pypi和uvx(推荐)
BASH```
1
2
3
4
5
6
7
8
9# Stdio mode
uvx —python 3.12 mcp-postgresql-ops
—type stdio
HTTP mode
uvx —python 3.12 mcp-postgresql-ops
—type streamable-http
—host 127.0.0.1
—port 8000
—log-level DEBUG
### (选项)配置多个PostgreSQL实例
JSON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26{
"mcpServers": {
"Postgresql-A": {
"command": "uvx",
"args": ["--python", "3.12", "mcp-postgresql-ops"],
"env": {
"POSTGRES_HOST": "a.foo.com",
"POSTGRES_PORT": "5432",
"POSTGRES_USER": "postgres",
"POSTGRES_PASSWORD": "postgres",
"POSTGRES_DB": "postgres"
}
},
"Postgresql-B": {
"command": "uvx",
"args": ["--python", "3.12", "mcp-postgresql-ops"],
"env": {
"POSTGRES_HOST": "b.bar.com",
"POSTGRES_PORT": "5432",
"POSTGRES_USER": "postgres",
"POSTGRES_PASSWORD": "postgres",
"POSTGRES_DB": "postgres"
}
}
}
}
/w本地来源
BASH```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24# Method 1: Module execution (for development, requires PYTHONPATH)
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops
—type stdio
Method 2: Direct script (after uv installation in project directory)
uv run mcp-postgresql-ops
—type stdio
Method 3: Installed package script (after pip/uv install)
mcp-postgresql-ops
—type stdio
HTTP mode examples:
Development mode
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops/src
python -m mcp_postgresql_ops
—type streamable-http
—host 127.0.0.1
—port 8000
—log-level DEBUG
Production mode (after installation)
mcp-postgresql-ops
—type streamable-http
—host 127.0.0.1
—port 8000
—log-level DEBUG
---
## CLI参数
- `--type`:运输类型(`stdio` 或 `streamable-http`)-默认值: `stdio`
- `--host`:HTTP传输的主机地址-默认值: `127.0.0.1`
- `--port`:HTTP传输的端口号-默认值: `8000`
- `--auth-enable`:为可流式传输的http模式启用承载令牌身份验证-默认值: `false`
- `--secret-key`:承载令牌身份验证的密钥(启用身份验证时需要)
- `--log-level`:日志记录级别(调试、信息、警告、错误、严重)-默认值: `INFO`
---
## 环境变量
| 变量 | 描述 | 默认值 | 项目默认值 |
| --- | --- | --- | --- |
| `PYTHONPATH` | Python模块搜索路径(仅在开发模式下需要) | - | `/app/src` |
| `MCP_LOG_LEVEL` | 服务器日志记录冗长(调试、信息、警告、错误) | `INFO` | `INFO` |
| `FASTMCP_TYPE` | MCP传输协议(用于CLI的stdio,用于web的流式http) | `stdio` | `streamable-http` |
| `FASTMCP_HOST` | HTTP服务器绑定地址(所有接口为0.0.0.0) | `127.0.0.1` | `0.0.0.0` |
| `FASTMCP_PORT` | 用于MCP通信的HTTP服务器端口 | `8000` | `8000` |
| `REMOTE_AUTH_ENABLE` | 为可流式传输的http模式启用承载令牌身份验证(默认值: `false` 如果未定义/为null/为空) | `false` | `false` |
| `REMOTE_SECRET_KEY` | 承载令牌身份验证的密钥(启用身份验证时需要) | - | `your-secret-key-here` |
| `PGSQL_VERSION` | PostgreSQL主要版本用于Docker镜像选择 | `17` | `17` |
| `PGDATA` | Docker容器内的PostgreSQL数据目录(**不要修改**) | `/var/lib/postgresql/data` | `/data/db` |
| `POSTGRES_HOST` | PostgreSQL服务器主机名或IP地址 | `127.0.0.1` | `host.docker.internal` |
| `POSTGRES_PORT` | PostgreSQL服务器端口号 | `5432` | `15432` |
| `POSTGRES_USER` | PostgreSQL连接用户名(需要读取权限) | `postgres` | `postgres` |
| `POSTGRES_PASSWORD` | PostgreSQL用户密码(支持特殊字符) | `changeme!@34` | `changeme!@34` |
| `POSTGRES_DB` | 连接的默认数据库名称 | `testdb` | `ecommerce` |
| `POSTGRES_MAX_CONNECTIONS` | PostgreSQL max_connections配置参数 | `200` | `200` |
| `DOCKER_EXTERNAL_PORT_OPENWEBUI` | Open WebUI容器的主机端口映射 | `8080` | `3003` |
| `DOCKER_EXTERNAL_PORT_MCP_SERVER` | MCP服务器容器的主机端口映射 | `8080` | `18003` |
| `DOCKER_EXTERNAL_PORT_MCPO_PROXY` | MCPO代理容器的主机端口映射 | `8000` | `8003` |
| `DOCKER_INTERNAL_PORT_POSTGRESQL` | PostgreSQL容器内部端口 | `5432` | `5432` |
**备注**: `POSTGRES_DB` 当没有指定特定数据库时,用作操作的默认目标数据库。在Docker环境中,如果设置为非默认名称,则此数据库将在PostgreSQL初始启动时自动创建。
**端口配置**:内置的PostgreSQL容器使用端口映射 `15432:5432` 哪里:
- `POSTGRES_PORT=15432`:用于主机访问和MCP服务器连接的外部端口
- `DOCKER_INTERNAL_PORT_POSTGRESQL=5432`:内部容器端口(PostgreSQL默认)
- 使用外部PostgreSQL服务器时,设置 `POSTGRES_PORT` 以匹配服务器的实际端口
---
## 先决条件
### 必需的PostgreSQL扩展
> 有关更多详细信息,请参阅 ##工具兼容性矩阵
**备注**:大多数MCP工具在没有任何PostgreSQL扩展的情况下工作。下面的部分。一些高级性能分析工具需要以下扩展:
SQL```
1
2
3
4-- Query performance statistics (required only for get_pg_stat_statements_top_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
-- Advanced monitoring (optional, used by get_pg_stat_monitor_recent_queries)
CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;
快速设置:对于新的PostgreSQL安装,请添加到 postgresql.conf:
1shared_preload_libraries = 'pg_stat_statements'
然后重新启动PostgreSQL并运行上面的CREATE EXTENSION命令。
pg_stat_statements仅适用于慢速查询分析工具。pg_stat_monitor是可选的,用于实时查询监控。- 所有其他工具都可以在没有这些扩展的情况下工作。
最低要求
- PostgreSQL 12+(用PostgreSQL 17和18测试)
- Python 3.12
- PostgreSQL服务器的网络访问
- 读取系统目录的权限
所需的PostgreSQL配置
⚠️ 统计数据收集设置: 一些MCP工具需要特定的PostgreSQL配置参数来收集统计数据。选择以下配置方法之一:
受这些设置影响的工具:
- get_user_functions_status:需要
track_functions = pl或track_functions = all - get_table_io_tasts & get_index_io_tasts:更精确的计时
track_io_timing = on - get_database_stats:通过以下方式增强I/O时序
track_io_timing = on
验证: 应用任何方法后,验证设置:
SQL```
1
2
3
4
5
6
7
8SELECT name, setting, context FROM pg_settings WHERE name IN (‘track_activities’, ‘track_counts’, ‘track_io_timing’, ‘track_functions’) ORDER BY name;
name | setting | context
------------------+---------+-----------
track_activities | on | superuser
track_counts | on | superuser
track_functions | pl | superuser
track_io_timing | on | superuser
(4 rows)
#### 方法1:postgresql.conf(推荐用于自管理postgresql)
将以下内容添加到您的 `postgresql.conf`:
INI```
1
2
3
4
5
6
7# Basic statistics collection (usually enabled by default)
track_activities = on
track_counts = on
# Required for function statistics tools
track_functions = pl # Enables PL/pgSQL function statistics collection
# Optional but recommended for accurate I/O timing
track_io_timing = on # Enables I/O timing statistics collection
然后重新启动PostgreSQL服务器。
方法2:PostgreSQL启动参数
对于Docker或命令行PostgreSQL启动:
BASH```
1
2
3
4
5
6
7
8
9
10
11
12
13
14# Docker example
docker run -d
-e POSTGRES_PASSWORD=mypassword
postgres:17
-c track_activities=on
-c track_counts=on
-c track_functions=pl
-c track_io_timing=on
Direct postgres command
postgres -D /data
-c track_activities=on
-c track_counts=on
-c track_functions=pl
-c track_io_timing=on
#### 方法3:动态配置(AWS RDS、Azure、GCP、托管服务)
对于无法修改的托管PostgreSQL服务 `postgresql.conf`,使用SQL命令动态更改设置:
SQL```
1
2
3
4
5
6
7
8
9-- Enable basic statistics collection (usually enabled by default)
ALTER SYSTEM SET track_activities = 'on';
ALTER SYSTEM SET track_counts = 'on';
-- Enable function statistics collection (requires superuser privileges)
ALTER SYSTEM SET track_functions = 'pl';
-- Enable I/O timing statistics (optional but recommended)
ALTER SYSTEM SET track_io_timing = 'on';
-- Reload configuration without restart (run separately)
SELECT pg_reload_conf();
会话级测试的替代方案:
SQL``` 1 2 3 4 5— Set for current session only (temporary) SET track_activities = ‘on’; SET track_counts = ‘on’; SET track_functions = ‘pl’; SET track_io_timing = ‘on’;
**备注**:使用命令行工具时,分别运行每个SQL语句以避免事务块错误。
---
## RDS/Aurora兼容性
- 此服务器是只读的,可以在RDS/Aurora上使用常规角色。对于高级分析,启用pg_stat_语句;pg_stat_monitor在托管引擎上不可用。
- 在RDS/Aurora上,对于持久设置,首选DB参数组而不是ALTER SYSTEM。
SQL```
1
2
3
4
5
6-- Verify preload setting
SHOW shared_preload_libraries;
-- Enable extension in target DB
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
-- Recommended visibility for monitoring
GRANT pg_read_all_stats TO <app_user>;
查询示例
🟢 独立于扩展的工具(始终可用)
-
get_server_info
-
“显示PostgreSQL服务器版本和扩展状态。”
-
“检查是否安装了pg_stat_语句。”
-
get_active_connections
-
“显示所有活动连接。”
-
“列出当前与数据库和用户的会话。”
-
get_postgresql_config
-
“显示所有PostgreSQL配置参数。”
-
“查找所有与内存相关的配置设置。”
-
get_tabase_list
-
“列出所有数据库及其大小。”
-
“显示包含所有者信息的数据库列表。”
-
get_table_list
-
“列出电子商务数据库中的所有表。”
-
“显示公共架构中的表大小。”
-
get_table_schema_info
-
“显示电子商务数据库中客户表的详细架构信息。”
-
“获取电子商务数据库中产品表的列详细信息和约束。”
-
“使用索引和外键分析电子商务数据库销售模式中订单表的表结构。”
-
“显示库存数据库公共架构中所有表的架构概述。”
-
📋 特性:列类型、约束、索引、外键、表元数据
-
⚠️ 必需:
database_name必须指定参数 -
get_database_schema_info
-
“显示电子商务数据库中的所有模式及其内容。”
-
“在电子商务数据库中获取有关销售模式的详细信息。”
-
“分析库存数据库的架构结构和权限。”
-
“显示hr_system数据库的架构概述,包括表计数和大小。”
-
📋 特性:架构所有者、权限、对象计数、大小、内容
-
⚠️ 必需:
database_name必须指定参数 -
get_table_关系
-
“显示电子商务数据库中客户表的所有关系。”
-
“分析电子商务数据库销售模式中订单表的外键关系。”
-
“获取电子商务数据库的数据库范围关系概述。”
-
“查找电子商务数据库中引用产品表的所有表。”
-
“显示库存数据库中的跨架构关系。”
-
📋 特性:外键关系(入站/出站)、跨模式依赖关系、约束详细信息
-
⚠️ 必需:
database_name必须指定参数 -
💡 用法:离开
table_name数据库范围的关系分析为空 -
get_user_list
-
“列出所有数据库用户及其角色。”
-
“显示特定数据库的用户权限。”
-
get_index_usage_stats
-
“分析索引使用效率。”
-
“查找当前数据库中未使用的索引。”
-
get_database_size_info
-
“显示数据库容量分析。”
-
“按大小查找最大的数据库。”
-
get_table_size_info
-
“显示表和索引大小分析。”
-
“在特定架构中查找最大的表。”
-
get_vacuum_analyze_status
-
“显示最近的VACUUM和ANALYZE操作。”
-
“列出需要VACUUM的表。”
-
get_current数据库信息
-
“我连接到哪个数据库?”
-
“显示当前数据库信息和连接详细信息。”
-
显示数据库编码、排序规则和大小信息
-
📋 特性:数据库名称、编码、排序规则、大小、连接限制
-
🔧 PostgreSQL 12-18:完全兼容,无需扩展
-
get_table_bloat_分析
-
“分析当前数据库中的表膨胀。”
-
“显示user_logs表模式的死元组比率和膨胀估计。”
-
“查找需要VACUUM维护的高膨胀表。”
-
“分析特定模式中至少有100个死元组的膨胀。”
-
📋 特性:死元组比率、膨胀大小估计、VACUUM建议、模式过滤
-
🔧 PostgreSQL 12-18:完全兼容,无需扩展
-
💡 用法:使用pg_stat_user_tables的独立扩展方法
-
get_database_bloat_overview
-
“按架构显示数据库范围的膨胀摘要。”
-
“获得跨所有模式的存储效率的高级视图。”
-
“确定需要维护注意的模式。”
-
📋 特性:架构级聚合、总膨胀估计、维护状态
-
🔧 PostgreSQL 12-18:完全兼容,无需扩展
-
获取autovacuum_status
-
“检查自动真空配置和触发条件。”
-
“显示需要立即自动吸尘的桌子。”
-
“分析公共架构的自动清空阈值百分比。”
-
“查找接近自动真空触发点的桌子。”
-
📋 特性:触发阈值分析、紧急程度分类、配置状态
-
🔧 PostgreSQL 12-18:完全兼容,无需扩展
-
💡 用法:使用pg_stat_user_tables进行独立于扩展的自动真空监测
-
获取autovacuum_activity
-
“显示过去48小时的自动吸尘器活动模式。”
-
“监控自动真空执行频率和时间。”
-
“查找具有不规则自动吸尘模式的桌子。”
-
“分析最近的自动吸尘器和自动分析历史。”
-
📋 特性:活动模式、执行频率、时间分析
-
🔧 PostgreSQL 12-18:完全兼容,无需扩展
-
💡 用法:历史自动真空模式分析
-
get_runing_vacuum_操作
-
“显示当前正在运行的VACUUM和ANALYZE操作。”
-
“监控主动维护操作及其进度。”
-
“检查是否有任何VACUUM操作正在阻止查询。”
-
“查找长时间运行的维护操作。”
-
📋 特性:实时运行状态、运行时间、影响程度、流程详细信息
-
🔧 PostgreSQL 12-18:完全兼容,无需扩展
-
💡 用法:使用pg_stat_activity进行实时维护监控
-
有效性分析
-
“分析VACUUM的有效性和维护模式。”
-
“比较手动真空与自动真空效率。”
-
“查找具有次优维护模式的表。”
-
“检查VACUUM频率与表活动比率。”
-
📋 特性:维护模式分析、有效性评估、DML与VACUUM比率
-
🔧 PostgreSQL 12-18:完全兼容,无需扩展
-
💡 用法:使用现有统计数据进行战略性真空分析
-
get_lock_monitoring
-
“显示所有当前锁定和阻止的会话。”
-
“仅显示具有授予=false筛选器的已阻止会话。”
-
“使用用户名筛选器按特定用户监视锁。”
-
“使用模式过滤器检查独占锁。”
-
获取_状态
-
“显示WAL状态和存档信息。”
-
“监控WAL生成和当前LSN位置。”
-
获取应用状态
-
“检查复制连接和延迟状态。”
-
“监视复制插槽和WAL接收器状态。”
-
get_database_stats
-
“显示全面的数据库性能指标。”
-
“分析事务提交率和I/O统计数据。”
-
“监视缓冲区缓存命中率和临时文件使用情况。”
-
get_bgwriter_status
-
“分析检查点性能和时间。”
-
“显示检查点性能。”
-
“显示后台编写器效率统计数据。”
-
“监视缓冲区分配和fsync模式。”
-
get_user_functions_status
-
“分析用户定义的函数性能。”
-
“显示函数调用计数和执行时间。”
-
“识别自定义函数中的性能瓶颈。”
-
⚠️ 需要:
track_functions = pl在postgresql.conf中 -
get_table_io_tasts
-
“分析表I/O性能和缓冲区命中率。”
-
“识别缓冲区缓存性能较差的表。”
-
“监视TOAST表I/O统计信息。”
-
💡 增强与:
track_io_timing = on精确计时 -
get_index_io_tasts
-
“显示索引I/O性能和缓冲区效率。”
-
“识别导致磁盘I/O过多的索引。”
-
“监视索引缓存友好性模式。”
-
💡 增强与:
track_io_timing = on精确计时 -
get_database_conconflicts_stats
-
“检查备用服务器上的复制冲突。”
-
“分析冲突类型和解决统计数据。”
-
“监视备用服务器查询取消模式。”
-
“监控WAL生成和当前LSN位置。”
-
获取应用状态
-
“检查复制连接和延迟状态。”
-
“监视复制插槽和WAL接收器状态。”
🚀 版本感知工具(自动适应)
-
get_iostats 新
-
“显示全面的I/O统计数据。”(PostgreSQL 16+提供了详细的细分)
-
“分析I/O统计数据。”
-
“分析缓冲区缓存效率和I/O时序。”
-
“按后端类型和上下文监视I/O模式。”
-
📈 第16页+:完整的pg_stat_io,包括时间、后端类型和上下文
-
📊 第12-15页:基本pg_statio_*回退,带缓冲区命中率
-
get_bgwriter_status (增强!)
-
“显示后台写入程序和检查点性能。”
-
📈 第17页+:通过以下方式分离检查指针和bgwriter统计信息
pg_stat_checkpointer -
📊 第12-16页:组合bgwriter统计数据(包括检查指针数据)
-
get_server_info (增强!)
-
“显示服务器版本和兼容性功能。”
-
“检查服务器兼容性。”
-
“检查此PostgreSQL版本上可用的MCP工具。”
-
“显示功能可用性矩阵和升级建议。”
-
get_all_tables_stats (增强!)
-
“显示所有表的综合统计数据。”(与PG12-18兼容的版本)
-
“使用Include_system=true参数包含系统表。”
-
“分析表访问模式和维护需求。”
-
📈 第13页+:跟踪真空后的插入情况(
n_ins_since_vacuum)优化维护计划 -
📊 第12页:对于不支持的列,兼容NULL模式
-
获取等待事件 新
-
“显示等待事件类型和描述。”
-
“此PostgreSQL版本上有哪些等待事件?”
-
📈 第17页+:本地
pg_wait_events带有完整描述的目录 -
📊 第12-16页:回退到
pg_stat_activity按类型分组的当前等待 -
get_wal_summarizer_status (新增!PG 17+)
-
“显示增量备份的WAL摘要器状态。”
-
“监控WAL总结进度。”
-
📈 第17页+:通过以下方式监控WAL汇总器
pg_get_wal_summarizer_state() -
❌ 第12-16页:不可用(返回信息性消息)
-
获取同步状态 (新增!PG 18+)
-
“显示异步I/O子系统状态。”
-
“监视pg_aios的异步I/O操作。”
-
📈 第18页+:
pg_aios异步I/O监控视图 -
❌ 第12-17页:不可用(返回信息性消息)
-
get_per-backend_io_tasts (新增!PG 18+)
-
“显示每个后端I/O和WAL统计信息。”
-
“按单个后端进程分析I/O模式。”
-
📈 第18页+:每个后端I/O统计数据和WAL统计数据
-
❌ 第12-17页:不可用(返回信息性消息)
🟡 扩展依赖工具
-
get_pg_stat_statements_top_查询 (需要
pg_stat_statements) -
“显示前10个最慢的查询。”
-
“分析库存数据库中的慢速查询。”
-
📈 版本兼容:PG12用途
total_time→total_exec_time测绘;PG13+使用本机列 -
💡 交叉版本:自动调整查询结构以兼容PostgreSQL 12-18
-
get_pg_stat_monitor_recent_查询 (可选,使用
pg_stat_monitor) -
“实时显示最近的查询。”
-
“监视过去5分钟的查询活动。”
-
📈 版本兼容:PG12用途
total_time→total_exec_time测绘;PG13+使用本机列 -
💡 交叉版本:自动调整查询结构以兼容PostgreSQL 12-18
💡 专业建议:所有工具都支持使用 database_name 参数。这允许PostgreSQL超级用户从单个MCP服务器实例分析和监视多个数据库。
故障排除
连接问题
- 检查PostgreSQL服务器状态
- 验证中的连接参数
.env文件 - 确保网络连接
- 检查用户权限
扩展错误
- 跑
get_server_info检查分机状态 - 安装缺少的扩展:
SQL``` 1 2CREATE EXTENSION pg_stat_statements; CREATE EXTENSION pg_stat_monitor;
3. 如果需要,重新启动PostgreSQL
### 配置问题
1. **函数统计“未找到数据”**:检查 `track_functions` 设置
SQL```
1SHOW track_functions; -- Should be 'pl' or 'all'
托管服务(AWS RDS等)的快速修复:
SQL``` 1 2ALTER SYSTEM SET track_functions = ‘pl’; SELECT pg_reload_conf();
2. **缺少I/O定时数据**:启用定时收集
SQL```
1SHOW track_io_timing; -- Should be 'on'
快速修复:
SQL``` 1 2ALTER SYSTEM SET track_io_timing = ‘on’; SELECT pg_reload_conf();
3. **应用配置更改**:
- **自我管理**:将设置添加到 `postgresql.conf` 并重新启动服务器
- **托管服务**:使用 `ALTER SYSTEM SET` + `SELECT pg_reload_conf()`
- **临时测试**:使用 `SET parameter = value` 本届会议
- 生成一些数据库活动以填充统计信息
### 性能问题
1. 使用 `limit` 减少结果大小的参数
2. 在非高峰时段运行监控
3. 运行分析之前检查数据库负载
### 版本兼容性问题
> 有关更多详细信息,请参阅 ##工具兼容性矩阵
1. **先运行兼容性检查**:
BASH```
1# "Use get_server_info to check version and available features"
- 了解功能可用性:
- PostgreSQL 18:所有功能,包括异步I/O、VACUUM定时、每个后端统计数据
- PostgreSQL 17:单独的检查指针统计数据、等待事件、WAL汇总器
- PostgreSQL 16:pg_stat_io视图
- PostgreSQL 14+:并行查询跟踪
- PostgreSQL 12-13:仅核心功能
- 如果工具显示“不可用”:
- 功能需要较新的PostgreSQL版本
- 工具将自动使用最佳可用替代方案
- 考虑升级PostgreSQL以增强监控
发展
测试与开发
BASH``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15# Clone and setup for development git clone https://github.com/call518/MCP-PostgreSQL-Ops.git cd MCP-PostgreSQL-Ops uv sync
Test with MCP Inspector (loads .env automatically)
./run-mcp-inspector-local.sh
Direct execution methods:
1. Using uv run (recommended for development)
uv run mcp-postgresql-ops —log-level DEBUG
2. Module execution (requires PYTHONPATH)
PYTHONPATH=src python -m mcp_postgresql_ops —log-level DEBUG
3. After installation
mcp-postgresql-ops —log-level DEBUG
Test version compatibility (requires different PostgreSQL versions)
Modify POSTGRES_HOST in .env to point to different versions
### 运行测试
有两个测试套件可供选择:
| 套件 | 文件 | 需要Docker |
| --- | --- | --- |
| 单元测试(版本兼容性逻辑) | `tests/test_version_compat.py` | 没有 |
| 集成测试(所有工具×PG 12–18) | `tests/test_tools_integration.py` | 是的 |
#### 选项A——使用单个命令运行所有内容(推荐)
`uv run pytest` 自动启动Docker测试容器(PG 12-18),等待它们完全初始化,运行所有测试,然后删除所有内容。
BASH```
1
2
3
4
5
6# Run all tests (unit + integration) — Docker is managed automatically
uv run pytest -v
# Unit tests only (no Docker needed)
uv run pytest tests/test_version_compat.py -v
# Integration tests only
uv run pytest tests/test_tools_integration.py -v
选项B——通过辅助脚本进行手动控制
BASH``` 1 2 3 4 5 6# Full run: docker up → wait → pytest → docker down uv run python scripts/run-tests.py
Pass pytest options directly
uv run python scripts/run-tests.py -v —tb=short
Keep containers running after tests (for debugging)
uv run python scripts/run-tests.py —no-cleanup
> **备注**:Docker必须正在运行。测试堆栈使用端口5412–5418(PG 12–18)。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38### Version Compatibility Testing The MCP server automatically adapts to PostgreSQL versions 12-18. To test across versions:
- Set up test databases: Different PostgreSQL versions (12, 14, 15, 16, 17, 18)
- Run compatibility tests: Point to each version and verify tool behavior
- Check feature detection: Ensure proper version detection and feature availability
- Verify fallback behavior: Confirm graceful degradation on older versions
Security Notes
- All tools are read-only - no data modification capabilities
- Sensitive information (passwords) are masked in outputs
- No direct SQL execution - only predefined queries
- Follows principle of least privilege
Contributing
🤝 Got ideas? Found bugs? Want to add cool features? We’re always excited to welcome new contributors! Whether you’re fixing a typo, adding a new monitoring tool, or improving documentation - every contribution makes this project better. Ways to contribute:
- 🐛 Report issues or bugs
- 💡 Suggest new PostgreSQL monitoring features
- 📝 Improve documentation
- 🚀 Submit pull requests
- ⭐ Star the repo if you find it useful!
Pro tip: The codebase is designed to be super friendly for adding new tools. Check out the existing
@mcp.tool()functions inmcp_main.py.
MCPO Swagger Docs
[MCPO Swagger URL] http://localhost:8003/postgresql-ops/docs
🔐 Security & Authentication
Bearer Token Authentication
For streamable-http mode, this MCP server supports Bearer token authentication to secure remote access. This is especially important when running the server in production environments.
Default Policy:
REMOTE_AUTH_ENABLEdefaults tofalseif undefined, null, or empty. This ensures backward compatibility and prevents startup errors when the variable is not set.
Configuration
Enable Authentication:
# In .env file
REMOTE_AUTH_ENABLE=true
REMOTE_SECRET_KEY=my-test-secret-key-12345
或者通过CLI:
BASH``` 1 2 3 4# Module method python -m mcp_postgresql_ops —type streamable-http —auth-enable —secret-key my-test-secret-key-12345
Script method
mcp-postgresql-ops —type streamable-http —auth-enable —secret-key my-test-secret-key-12345
#### 安全级别
1. **stdio模式** (默认):仅本地访问,无需身份验证
2. **可流式传输http+REMOTE_AUTH_ENABLE=false**:无身份验证的远程访问⚠️ **不建议用于生产**
3. **可流式传输http+REMOTE_AUTH_ENABLE=true**:使用承载令牌身份验证进行远程访问✅ **建议用于生产**
#### 客户端配置
启用身份验证后,MCP客户端必须在授权标头中包含Bearer令牌:
JSON```
1
2
3
4
5
6
7
8
9
10
11{
"mcpServers": {
"mcp-postgresql-ops": {
"type": "streamable-http",
"url": "http://your-server:8000/mcp",
"headers": {
"Authorization": "Bearer my-test-secret-key-12345"
}
}
}
}
安全最佳实践
- 始终启用身份验证 在生产环境中使用流式http模式时
- 使用强随机生成的密钥 (建议使用32+个字符)
- 使用HTTPS 如果可能(使用SSL/TLS配置反向代理)
- 限制网络访问 使用防火墙或网络策略
- 定期旋转密钥 增强安全性
- 监控访问日志 未经授权的访问尝试
错误处理
当身份验证失败时,服务器返回:
- 401未经授权 用于丢失或无效的令牌
- 详细的错误消息 JSON格式用于调试
🚀 添加自定义工具
此MCP服务器旨在易于扩展。按照以下4个简单步骤添加您自己的自定义工具:
分步指南
1. 添加辅助函数(可选)
添加可重用的数据函数 src/mcp_postgresql_ops/functions.py:
PYTHON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22async def get_your_custom_data(target_database: str = None, limit: int = 20) -> List[Dict[str, Any]]: """Your custom data retrieval function.""" try: # Example implementation - adapt to your PostgreSQL needs query = """ SELECT schemaname, tablename, attname as column_name, n_distinct, most_common_vals, most_common_freqs FROM pg_stats WHERE schemaname NOT IN (‘information_schema’, ‘pg_catalog’) ORDER BY schemaname, tablename, attname LIMIT $1 """ results = await execute_query(query, [limit], database=target_database) return results except Exception as e: logger.error(f”Failed to get custom data: {e}”) raise
#### 2. **创建您的MCP工具**
将您的工具功能添加到 `src/mcp_postgresql_ops/mcp_main.py`:
PYTHON```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29@mcp.tool()
async def get_your_custom_analysis(limit: int = 50, database_name: Optional[str] = None) -> str:
"""
[Tool Purpose]: Brief description of what your tool does
[Exact Functionality]:
- Feature 1: Data aggregation and analysis
- Feature 2: Database monitoring and insights
- Feature 3: Performance metrics and reporting
[Required Use Cases]:
- When user asks "your specific analysis request"
- Your PostgreSQL-specific monitoring needs
Args:
limit: Maximum results (1-100)
database_name: Target database name (optional, uses default if not specified)
Returns:
Formatted analysis results
"""
try:
# Always validate input limits
limit = max(1, min(limit, 100))
# Get your custom data
results = await get_your_custom_data(target_database=database_name, limit=limit)
if not results:
return "No data found for custom analysis."
# Format and return results
return format_table_data(results, f"Custom Analysis Results (Top {len(results)})")
except Exception as e:
logger.error(f"Failed to get custom analysis: {e}")
return f"Error: {str(e)}"
3. 更新导入
将辅助函数添加到中的导入部分 src/mcp_postgresql_ops/mcp_main.py (第30行附近):
PYTHON``` 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17from .functions import ( execute_query, execute_single_query, format_table_data, format_bytes, format_duration, get_server_version, check_extension_exists, get_pg_stat_statements_data, get_pg_stat_monitor_data, sanitize_connection_info, read_prompt_template, parse_prompt_sections, get_current_database_name, POSTGRES_CONFIG, get_your_custom_data, # Add your new function here )
#### 4. **更新提示模板(推荐)**
将您的工具描述添加到 `src/mcp_postgresql_ops/prompt_template.md` 为了更好地识别自然语言:
MARKDOWN```
1
2
3
4
5
6
7### **Your Custom Analysis Tool**
### X. **get_your_custom_analysis**
**Purpose**: Brief description of what your tool does
**Usage**: "Show me your custom analysis" or "Get custom analysis for database_name"
**Features**: Data aggregation, database monitoring, performance metrics
**Optional**: `database_name` parameter for specific database analysis
**Limit**: Results limited to 1-100 records for performance
5. 测试你的工具
BASH``` 1 2 3 4 5 6 7 8 9# Local testing with MCP Inspector ./run-mcp-inspector-local.sh
Or test with Docker stack
docker-compose up -d docker-compose logs -f mcp-server
Test with natural language queries:
“Show me your custom analysis"
"Get custom analysis for ecommerce database"
"Analyze custom data with limit 25”
### 重要说明
- **多数据库支持**:所有工具都支持可选 `database_name` 针对特定数据库的参数
- **输入验证**:始终验证 `limit` 参数与 `max(1, min(limit, 100))`
- **错误处理**:返回用户友好的错误消息,而不是引发异常
- **日志记录**:使用 `logger.error()` 用于调试,同时向用户返回干净的错误消息
- **PostgreSQL兼容性**:您的自定义查询应该在PostgreSQL 12-18中工作
- **扩展依赖关系**:如果您的工具需要特定的扩展,请通过以下方式检查可用性 `check_extension_exists()`
### 高级模式
对于版本感知查询或依赖扩展的功能,请参阅现有的工具,如 `get_pg_stat_statements_top_queries` 作为参考图案。
就是这样!您的自定义工具已准备好通过任何MCP客户端与自然语言查询一起使用。
---
## 许可证
自由使用、修改和分发 **MIT许可证**.
---
## ⭐ 其他项目
**同一作者的其他MCP服务器:**
- [MCP-气流API](https://github.com/call518/MCP-Airflow-API)
- [MCP-Ambari-API公司](https://github.com/call518/MCP-Ambari-API)
- [MCP-OpenStack-API](https://github.com/call518/MCP-OpenStack-API)
- [LogSentinelAI-基于LLB的日志分析器](https://github.com/call518/LogSentinelAI) 