Mcp Postgresql Ops

数据库 Python

🚀 PostgreSQL操作与监控MCP服务器

MCP-PostgreSQL-Ops 是一款专业的MCP服务器，用于对PostgreSQL数据库进行操作、监控和管理。它支持PostgreSQL 12 - 17版本，可通过自然语言查询实现全面的数据库分析、性能监控以及智能维护建议。大部分功能可独立运行，但在安装 pg_stat_statements 和（可选）pg_stat_monitor 扩展后，高级查询分析功能将得到增强。

✨ 主要特性

✅ 零配置：可直接与PostgreSQL 12 - 17版本配合使用，自动检测版本。
✅ 自然语言交互：支持使用自然语言提问，例如 “显示慢查询” 或 “分析表膨胀情况”。
✅ 生产环境安全：仅执行只读操作，兼容RDS/Aurora，普通用户权限即可使用。
✅ 扩展增强：可选安装 pg_stat_statements 和 pg_stat_monitor 扩展，以实现高级查询分析。
✅ 全面的数据库监控：提供性能分析、表膨胀检测和维护建议。
✅ 智能查询分析：通过集成 pg_stat_statements 和 pg_stat_monitor 识别慢查询。
✅ 模式与关系发现：探索数据库结构，提供详细的关系映射。
✅ VACUUM与自动清理智能分析：实时监控维护操作并分析其有效性。
✅ 多数据库操作：无缝进行跨数据库分析和监控。
✅ 企业级适用：安全的只读操作，兼容RDS/Aurora。
✅ 开发者友好：代码结构简单，易于定制和扩展工具功能。

🔧 高级功能

支持版本感知的I/O统计（在PostgreSQL 16+版本中增强）。
实时监控连接和锁状态。
分析后台进程和检查点。
监控复制状态和WAL日志。
分析数据库容量和表膨胀情况。

🚀 快速开始

⚠️ 重要提示

docker-compose.yml 中包含的 postgresql 容器仅用于快速启动测试。您可以根据需要调整环境变量，连接到自己的PostgreSQL实例。

💡 使用建议

若要使用自己的PostgreSQL实例而非内置测试容器，请按以下步骤操作：

更新 .env 文件中的目标PostgreSQL连接信息（请参考 POSTGRES_HOST、POSTGRES_PORT、POSTGRES_USER、POSTGRES_PASSWORD、POSTGRES_DB）。

在 docker-compose.yml 中注释掉（禁用）postgres 和 postgres-init-extensions 容器，以避免启动内置测试数据库。

1. 环境设置

⚠️ 重要提示

虽然超级用户权限可以访问所有数据库和系统信息，但MCP服务器使用普通用户权限也能执行基本的监控任务。

git clone https://github.com/call518/MCP-PostgreSQL-Ops.git
cd MCP-PostgreSQL-Ops

### 检查并修改.env文件
cp .env.example .env
vim .env

### 无需修改默认值，但如果使用自己的PostgreSQL服务器，请编辑以下内容：
POSTGRES_HOST=host.docker.internal
POSTGRES_PORT=15432  # 主机访问的外部端口（映射到内部5432）
POSTGRES_USER=postgres
POSTGRES_PASSWORD=changeme!@34
POSTGRES_DB=ecommerce # 默认连接的数据库。超级用户可以访问所有数据库。

⚠️ 重要提示

PGDATA=/data/db 是为Percona PostgreSQL Docker镜像预先配置的，该镜像需要此特定路径以确保正确的写入权限。

2. 启动演示容器

# 启动所有容器，包括内置的PostgreSQL进行测试
docker-compose up -d

# 替代方案：如果使用自己的PostgreSQL实例
# 在docker-compose.yml中注释掉postgres和postgres-init-extensions服务
# 然后使用自定义配置：
# docker-compose -f docker-compose.custom-db.yml up -d

⚠️ 重要提示

初始环境设置需要几分钟时间，因为容器按以下顺序启动：

PostgreSQL 容器首先启动并初始化数据库。

PostgreSQL扩展 容器安装扩展并创建全面的测试数据（约83K条记录）。

MCP服务器 和 MCPO代理 容器在PostgreSQL准备好后启动。

OpenWebUI 容器最后启动，加载Web界面可能需要额外的时间。

💡 使用建议

运行 docker-compose up -d 后等待2 - 3分钟再访问OpenWebUI，以确保所有服务完全初始化。

🔍 检查容器状态（可选）：

# 监控容器启动进度
docker-compose logs -f

# 检查所有容器是否正在运行
docker-compose ps

# 验证PostgreSQL是否准备好
docker-compose logs postgres | grep "ready to accept connections"

3. 访问OpenWebUI

访问地址：http://localhost:3003/

由 swagger 提供的MCP工具功能列表可在MCPO API文档URL中找到。
- 例如：http://localhost:8003/docs

4. 在OpenWebUI中注册工具

使用管理员账户登录OpenWebUI。
从顶部菜单中选择 “设置” → “工具”。
输入 postgresql-ops 工具地址（例如，http://localhost:8003/postgresql-ops）以连接MCP工具。
设置Ollama或OpenAI。

5. 完成！

恭喜！ 您的MCP PostgreSQL操作服务器现已可以使用。您可以开始使用自然语言查询探索您的数据库。

🚀 尝试以下示例查询：

“显示当前活动连接”
“系统中最慢的查询有哪些？”
“分析所有数据库中的表膨胀情况”
“显示数据库大小信息”
“哪些表需要进行VACUUM维护？”

💻 使用示例

Claude桌面集成

（推荐）将以下内容添加到您的Claude桌面配置文件中：

{
"mcpServers": {
"postgresql-ops": {
"command": "uvx",
"args": ["--python", "3.11", "mcp-postgresql-ops"],
"env": {
"POSTGRES_HOST": "127.0.0.1",
"POSTGRES_PORT": "15432",
"POSTGRES_USER": "postgres",
"POSTGRES_PASSWORD": "changeme!@34",
"POSTGRES_DB": "ecommerce"
}
}
}
}

（可选）使用本地源代码运行：

{
"mcpServers": {
"postgresql-ops": {
"command": "uv",
"args": ["run", "python", "-m", "src.mcp_postgresql_ops.mcp_main"],
"env": {
"PYTHONPATH": "/path/to/MCP-PostgreSQL-Ops",
"POSTGRES_HOST": "127.0.0.1",
"POSTGRES_PORT": "15432",
"POSTGRES_USER": "postgres",
"POSTGRES_PASSWORD": "changeme!@34",
"POSTGRES_DB": "ecommerce"
}
}
}
}

独立运行MCP服务器

使用Pypi和uvx（推荐）

# 标准输入输出模式
uvx --python 3.11 mcp-postgresql-ops \
--type stdio

# HTTP模式
uvx --python 3.11 mcp-postgresql-ops \
--type streamable-http \
--host 127.0.0.1 \
--port 8080 \
--log-level DEBUG

（可选）配置多个PostgreSQL实例

{
"mcpServers": {
"Postgresql-A": {
"command": "uvx",
"args": ["--python", "3.11", "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.11", "mcp-postgresql-ops"],
"env": {
"POSTGRES_HOST": "b.bar.com",
"POSTGRES_PORT": "5432",
"POSTGRES_USER": "postgres",
"POSTGRES_PASSWORD": "postgres",
"POSTGRES_DB": "postgres"
}
}
}
}

使用本地源代码

# 标准输入输出模式
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops
python -m src.mcp_postgresql_ops.mcp_main \
--type stdio

# HTTP模式
PYTHONPATH=/path/to/MCP-PostgreSQL-Ops
python -m src.mcp_postgresql_ops.mcp_main \
--type streamable-http \
--host 127.0.0.1 \
--port 8080 \
--log-level DEBUG

📚 详细文档

环境变量

属性	详情
`PYTHONPATH`	MCP服务器导入Python模块的搜索路径
`MCP_LOG_LEVEL`	服务器日志详细程度（DEBUG、INFO、WARNING、ERROR）
`FASTMCP_TYPE`	MCP传输协议（stdio用于CLI，streamable-http用于Web）
`FASTMCP_HOST`	HTTP服务器绑定地址（0.0.0.0表示所有接口）
`FASTMCP_PORT`	MCP通信的HTTP服务器端口
`PGSQL_VERSION`	用于选择Docker镜像的PostgreSQL主版本
`PGDATA`	Docker容器内的PostgreSQL数据目录（请勿修改）
`POSTGRES_HOST`	PostgreSQL服务器主机名或IP地址
`POSTGRES_PORT`	PostgreSQL服务器端口号
`POSTGRES_USER`	PostgreSQL连接用户名（需要读取权限）
`POSTGRES_PASSWORD`	PostgreSQL用户密码（支持特殊字符）
`POSTGRES_DB`	连接的默认数据库名称
`POSTGRES_MAX_CONNECTIONS`	PostgreSQL的 `max_connections` 配置参数
`DOCKER_EXTERNAL_PORT_OPENWEBUI`	Open WebUI容器的主机端口映射
`DOCKER_EXTERNAL_PORT_MCP_SERVER`	MCP服务器容器的主机端口映射
`DOCKER_EXTERNAL_PORT_MCPO_PROXY`	MCPO代理容器的主机端口映射
`DOCKER_INTERNAL_PORT_POSTGRESQL`	PostgreSQL容器的内部端口

⚠️ 重要提示

POSTGRES_DB 是在未指定特定数据库时操作的默认目标数据库。在Docker环境中，如果设置为非默认名称，该数据库将在PostgreSQL首次启动时自动创建。

💡 使用建议

内置的PostgreSQL容器使用端口映射 15432:5432，其中：

POSTGRES_PORT = 15432：主机访问和MCP服务器连接的外部端口。

DOCKER_INTERNAL_PORT_POSTGRESQL = 5432：容器内部端口（PostgreSQL默认）。

使用外部PostgreSQL服务器时，请将 POSTGRES_PORT 设置为与服务器实际端口匹配。

先决条件

所需的PostgreSQL扩展

⚠️ 重要提示

有关更多详细信息，请参阅工具兼容性矩阵。

💡 使用建议

大多数MCP工具无需任何PostgreSQL扩展即可工作。一些高级性能分析工具需要以下扩展：

-- 查询性能统计（仅 `get_pg_stat_statements_top_queries` 需要）
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 高级监控（可选，`get_pg_stat_monitor_recent_queries` 使用）
CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;

⚠️ 重要提示

对于新的PostgreSQL安装，在 postgresql.conf 中添加以下内容：

shared_preload_libraries = 'pg_stat_statements'

然后重启PostgreSQL并运行上述 CREATE EXTENSION 命令。

pg_stat_statements 仅用于慢查询分析工具。
pg_stat_monitor 是可选的，用于实时查询监控。
所有其他工具无需这些扩展即可工作。

最低要求

PostgreSQL 12+（已在PostgreSQL 17上测试）
Python 3.11
能够访问PostgreSQL服务器的网络连接
对系统目录的读取权限

所需的PostgreSQL配置

⚠️ 重要提示

一些MCP工具需要特定的PostgreSQL配置参数来收集统计信息。请选择以下配置方法之一：

💡 使用建议

受这些设置影响的工具：

get_user_functions_stats：需要 track_functions = pl 或 track_functions = all。

get_table_io_stats 和 get_index_io_stats：track_io_timing = on 可提供更准确的计时。

get_database_stats：track_io_timing = on 可增强I/O计时。

⚠️ 重要提示

应用任何方法后，验证设置：

SELECT 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 中添加以下内容：

# 基本统计信息收集（通常默认启用）
track_activities = on
track_counts = on

# 函数统计工具所需
track_functions = pl    # 启用PL/pgSQL函数统计信息收集

# 可选但推荐用于准确的I/O计时
track_io_timing = on    # 启用I/O计时统计信息收集

然后重启PostgreSQL服务器。

方法2：PostgreSQL启动参数

对于Docker或命令行启动的PostgreSQL：

# Docker示例
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

# 直接使用postgres命令
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.conf 的托管PostgreSQL服务，使用SQL命令动态更改设置：

-- 启用基本统计信息收集（通常默认启用）
ALTER SYSTEM SET track_activities = 'on';
ALTER SYSTEM SET track_counts = 'on';

-- 启用函数统计信息收集（需要超级用户权限）
ALTER SYSTEM SET track_functions = 'pl';

-- 启用I/O计时统计信息（可选但推荐）
ALTER SYSTEM SET track_io_timing = 'on';

-- 不重启重新加载配置（单独运行）
SELECT pg_reload_conf();

💡 使用建议

会话级测试的替代方法：

-- 仅为当前会话设置（临时）
SET track_activities = 'on';
SET track_counts = 'on';
SET track_functions = 'pl';
SET track_io_timing = 'on';

⚠️ 重要提示

使用命令行工具时，分别运行每个SQL语句，以避免事务块错误。

RDS/Aurora兼容性

此服务器为只读模式，可与RDS/Aurora上的普通角色配合使用。若要进行高级分析，请启用 pg_stat_statements；pg_stat_monitor 在托管引擎上不可用。
在RDS/Aurora上，建议使用数据库参数组而非 ALTER SYSTEM 进行持久设置。

-- 验证预加载设置
SHOW shared_preload_libraries;

-- 在目标数据库中启用扩展
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;

-- 推荐的监控可见性
GRANT pg_read_all_stats TO <app_user>;

示例查询

🟢 无需扩展的工具（始终可用）

get_server_info
- “显示PostgreSQL服务器版本和扩展状态。”
- “检查是否安装了 pg_stat_statements。”
get_active_connections
- “显示所有活动连接。”
- “列出当前会话的数据库和用户信息。”
get_postgresql_config
- “显示所有PostgreSQL配置参数。”
- “查找所有与内存相关的配置设置。”
get_database_list
- “列出所有数据库及其大小。”
- “显示带有所有者信息的数据库列表。”
get_table_list
- “列出 ecommerce 数据库中的所有表。”
- “显示 public 模式下表的大小。”
get_table_schema_info
- “显示 ecommerce 数据库中 customers 表的详细模式信息。”
- “获取 ecommerce 数据库中 products 表的列详细信息和约束。”
- “分析 ecommerce 数据库 sales 模式中 orders 表的表结构，包括索引和外键。”
- “显示 inventory 数据库 public 模式中所有表的模式概述。”
- 📋 功能：列类型、约束、索引、外键、表元数据
- ⚠️ 必需：必须指定 database_name 参数
get_database_schema_info
- “显示 ecommerce 数据库中所有模式及其内容。”
- “获取 ecommerce 数据库中 sales 模式的详细信息。”
- “分析 inventory 数据库的模式结构和权限。”
- “显示 hr_system 数据库的模式概述，包括表计数和大小。”
- 📋 功能：模式所有者、权限、对象计数、大小、内容
- ⚠️ 必需：必须指定 database_name 参数
get_table_relationships
- “显示 ecommerce 数据库中 customers 表的所有关系。”
- “分析 ecommerce 数据库 sales 模式中 orders 表的外键关系。”
- “获取 ecommerce 数据库的全数据库关系概述。”
- “查找 ecommerce 数据库中引用 products 表的所有表。”
- “显示 inventory 数据库中的跨模式关系。”
- 📋 功能：外键关系（入站/出站）、跨模式依赖关系、约束详细信息
- ⚠️ 必需：必须指定 database_name 参数
- 💡 使用方法：留空 table_name 可进行全数据库关系分析
get_user_list
- “列出所有数据库用户及其角色。”
- “显示特定数据库的用户权限。”
get_index_usage_stats
- “分析索引使用效率。”
- “查找当前数据库中未使用的索引。”
get_database_size_info
- “显示数据库容量分析。”
- “查找按大小排序的最大数据库。”
get_table_size_info
- “显示表和索引大小分析。”
- “查找特定模式中最大的表。”
get_vacuum_analyze_stats
- “显示最近的VACUUM和ANALYZE操作。”
- “列出需要VACUUM的表。”
get_current_database_info
- “我当前连接到哪个数据库？”
- “显示当前数据库信息和连接详细信息。”
- “显示数据库编码、排序规则和大小信息。”
- 📋 功能：数据库名称、编码、排序规则、大小、连接限制
- 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
get_table_bloat_analysis
- “分析当前数据库中的表膨胀情况。”
- “显示 ecommerce 数据库中死元组比率较高的表。”
- “查找需要VACUUM维护的表。”
- “检查死元组超过5000个的表的膨胀情况。”
- 📋 功能：死元组比率、估计的膨胀大小、VACUUM建议
- ⚠️ 必需：跨数据库分析时必须指定 database_name
get_database_bloat_overview
- “按模式显示全数据库的膨胀摘要。”
- “获取 inventory 数据库的膨胀概述。”
- “识别膨胀比率最高的模式。”
- “根据膨胀统计信息进行数据库维护规划。”
- 📋 功能：模式级聚合、维护优先级、大小建议
get_autovacuum_status
- “检查自动清理配置和触发条件。”
- “显示需要立即进行自动清理的表。”
- “分析 public 模式的自动清理阈值百分比。”
- “查找接近自动清理触发点的表。”
- 📋 功能：触发阈值分析、紧急程度分类、配置状态
- 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
- 💡 使用方法：使用 pg_stat_user_tables 进行无需扩展的自动清理监控
get_autovacuum_activity
- “显示过去48小时的自动清理活动模式。”
- “监控自动清理执行频率和时间。”
- “查找自动清理模式不规则的表。”
- “分析最近的自动清理和自动分析历史。”
- 📋 功能：活动模式、执行频率、时间分析
- 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
- 💡 使用方法：历史自动清理模式分析
get_running_vacuum_operations
- “显示当前正在运行的VACUUM和ANALYZE操作。”
- “监控活动的维护操作及其进度。”
- “检查是否有VACUUM操作阻塞查询。”
- “查找长时间运行的维护操作。”
- 📋 功能：实时操作状态、已用时间、影响级别、进程详细信息
- 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
- 💡 使用方法：使用 pg_stat_activity 进行实时维护监控
get_vacuum_effectiveness_analysis
- “分析VACUUM有效性和维护模式。”
- “比较手动VACUUM和自动清理的效率。”
- “查找维护模式不佳的表。”
- “检查VACUUM频率与表活动比率。”
- 📋 功能：维护模式分析、有效性评估、DML与VACUUM比率
- 🔧 PostgreSQL 12 - 17：完全兼容，无需扩展
- 💡 使用方法：使用现有统计信息进行战略性VACUUM分析
get_table_bloat_analysis
- “分析 public 模式中的表膨胀情况。”
- “显示 ecommerce 数据库中死元组比率较高的表。”
- “查找需要VACUUM维护的表。”
- “检查死元组超过5000个的表的膨胀情况。”
- 📋 功能：死元组比率、估计的膨胀大小、VACUUM建议
- ⚠️ 必需：跨数据库分析时必须指定 database_name
get_database_bloat_overview
- “按模式显示全数据库的膨胀摘要。”
- “获取 inventory 数据库的膨胀概述。”
- “识别膨胀比率最高的模式。”
- “根据膨胀统计信息进行数据库维护规划。”
- 📋 功能：模式级聚合、维护优先级、大小建议
get_lock_monitoring
- “显示所有当前锁和阻塞的会话。”
- “仅显示 granted = false 过滤后的阻塞会话。”
- “使用用户名过滤器按特定用户监控锁。”
- “使用模式过滤器检查排他锁。”
get_wal_status
- “显示WAL状态和归档信息。”
- “监控WAL生成和当前LSN位置。”
get_replication_status
- “检查复制连接和延迟状态。”
- “监控复制槽和WAL接收器状态。”
get_database_stats
- “显示全面的数据库性能指标。”
- “分析事务提交比率和I/O统计信息。”
- “监控缓冲区缓存命中率和临时文件使用情况。”
get_bgwriter_stats
- “分析检查点性能和时间。”
- “显示检查点性能。”
- “显示后台写入器效率统计信息。”
- “监控缓冲区分配和fsync模式。”
get_user_functions_stats
- “分析用户定义函数的性能。”
- “显示函数调用计数和执行时间。”
- “识别自定义函数中的性能瓶颈。”
- ⚠️ 需要：postgresql.conf 中 track_functions = pl
get_table_io_stats
- “分析表I/O性能和缓冲区命中率。”
- “识别缓冲区缓存性能不佳的表。”
- “监控TOAST表的I/O统计信息。”
- 💡 增强功能：track_io_timing = on 可提供更准确的计时
get_index_io_stats
- “显示索引I/O性能和缓冲区效率。”
- “识别导致过多磁盘I/O的索引。”
- “监控索引缓存友好性模式。”
- 💡 增强功能：track_io_timing = on 可提供更准确的计时
get_database_conflicts_stats
- “检查备用服务器上的复制冲突。”
- “分析冲突类型和解决统计信息。”
- “监控备用服务器查询取消模式。”
- “监控WAL生成和当前LSN位置。”
get_replication_status
- “检查复制连接和延迟状态。”
- “监控复制槽和WAL接收器状态。”

🚀 版本感知工具（自动适应）

get_io_stats（新增！）
- “显示全面的I/O统计信息。”（PostgreSQL 16+提供详细细分）
- “分析I/O统计信息。”
- “分析缓冲区缓存效率和I/O时间。”
- “按后端类型和上下文监控I/O模式。”
- 📈 PG16+：完整的 pg_stat_io 支持，包括计时、后端类型和上下文
- 📊 PG12 - 15：基本的 pg_statio_* 回退，提供缓冲区命中率
get_bgwriter_stats（增强！）
- “显示后台写入器和检查点性能。”
- 📈 PG15：单独的检查点器和后台写入器统计信息（独特功能）
- 📊 PG12 - 14, 16+：合并的后台写入器统计信息（包括检查点器数据）
get_server_info（增强！）
- “显示服务器版本和兼容性功能。”
- “检查服务器兼容性。”
- “检查此PostgreSQL版本上可用的MCP工具。”
- “显示功能可用性矩阵和升级建议。”
get_all_tables_stats（增强！）
- “显示所有表的全面统计信息。”（PG12 - 17版本兼容）
- “使用 include_system = true 参数包括系统表。”
- “分析表访问模式和维护需求。”
- 📈 PG13+：跟踪自上次VACUUM以来的插入次数（n_ins_since_vacuum），以优化维护计划
- 📊 PG12：兼容模式，不支持的列显示为NULL

🟡 需要扩展的工具

get_pg_stat_statements_top_queries（需要 pg_stat_statements）
- “显示前10个最慢的查询。”
- “分析 inventory 数据库中的慢查询。”
- 📈 版本兼容：PG12使用 total_time → total_exec_time 映射；PG13+使用原生列
- 💡 跨版本：自动调整查询结构以兼容PostgreSQL 12 - 17
get_pg_stat_monitor_recent_queries（可选，使用 pg_stat_monitor）
- “实时显示最近的查询。”
- “监控过去5分钟的查询活动。”
- 📈 版本兼容：PG12使用 total_time → total_exec_time 映射；PG13+使用原生列
- 💡 跨版本：自动调整查询结构以兼容PostgreSQL 12 - 17

💡 使用建议

所有工具都支持使用 database_name 参数进行多数据库操作。这允许PostgreSQL超级用户从单个MCP服务器实例分析和监控多个数据库。

工具兼容性矩阵

🟢 无需扩展的工具（始终可用）

工具名称	是否需要扩展	PG 12	PG 13	PG 14	PG 15	PG 16	PG 17	使用的系统视图/表
`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_table_bloat_analysis`	❌ 无需扩展	✅	✅	✅	✅	✅	✅	`pg_stat_user_tables`
`get_database_bloat_overview`	❌ 无需扩展	✅	✅	✅	✅	✅	✅	`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	特殊功能
`get_io_stats`	❌ 无需扩展	✅ 基本功能	✅ 基本功能	✅ 基本功能	✅ 基本功能	✅ 增强功能	✅ 增强功能	PG16+：支持 `pg_stat_io`
`get_bgwriter_stats`	❌ 无需扩展	✅	✅	✅	✅ 特殊功能	✅	✅	PG15：单独的检查点器统计信息
`get_replication_status`	❌ 无需扩展	✅ 兼容	✅ 增强功能	✅ 增强功能	✅ 增强功能	✅ 增强功能	✅ 增强功能	PG13+：`wal_status`、`safe_wal_size`；PG16+：增强的WAL接收器
`get_all_tables_stats`	❌ 无需扩展	✅ 兼容	✅ 增强功能	✅ 增强功能	✅ 增强功能	✅ 增强功能	✅ 增强功能	PG13+：跟踪自上次VACUUM以来的插入次数（`n_ins_since_vacuum`），以优化维护计划
`get_user_functions_stats`	⚙️ 需要配置	✅	✅	✅	✅	✅	✅	需要 `track_functions = pl`

🟡 需要扩展的工具

工具名称	需要的扩展	PG 12	PG 13	PG 14	PG 15	PG 16	PG 17	注意事项
`get_pg_stat_statements_top_queries`	`pg_stat_statements`	✅ 兼容	✅ 增强功能	✅ 增强功能	✅ 增强功能	✅ 增强功能	✅ 增强功能	PG12：`total_time` → `total_exec_time`；PG13+：原生 `total_exec_time`
`get_pg_stat_monitor_recent_queries`	`pg_stat_monitor`	✅ 兼容	✅ 增强功能	✅ 增强功能	✅ 增强功能	✅ 增强功能	✅ 增强功能	PG12：`total_time` → `total_exec_time`；PG13+：原生 `total_exec_time`

⚠️ 重要提示

PostgreSQL 18支持：PostgreSQL 18目前处于测试阶段，Percona Distribution PostgreSQL尚未支持。待PostgreSQL 18达到稳定版本并提供发行版支持后，将添加相应支持。

故障排除

连接问题

检查PostgreSQL服务器状态。
验证 .env 文件中的连接参数。
确保网络连接正常。
检查用户权限。

扩展错误

运行 get_server_info 检查扩展状态。
安装缺失的扩展：

CREATE EXTENSION pg_stat_statements;
CREATE EXTENSION pg_stat_monitor;

如有需要，重启PostgreSQL。

配置问题

函数统计信息显示 “未找到数据”：检查 track_functions 设置

SHOW track_functions;  -- 应为 'pl' 或 'all'

💡 使用建议

托管服务（如AWS RDS等）的快速修复方法：

ALTER SYSTEM SET track_functions = 'pl';
SELECT pg_reload_conf();

缺少I/O计时数据：启用计时收集

SHOW track_io_timing;  -- 应为 'on'

💡 使用建议

快速修复方法：

ALTER SYSTEM SET track_io_timing = 'on';
SELECT pg_reload_conf();

应用配置更改：

自管理：将设置添加到 postgresql.conf 并重启服务器。
托管服务：使用 ALTER SYSTEM SET + SELECT pg_reload_conf()。
临时测试：使用 SET parameter = value 为当前会话设置。
生成一些数据库活动以填充统计信息。

性能问题

使用 limit 参数减少结果集大小。
在非高峰时段运行监控。
在运行分析之前检查数据库负载。

版本兼容性问题

⚠️ 重要提示

有关更多详细信息，请参阅工具兼容性矩阵。

首先运行兼容性检查：

# "使用 get_server_info 检查版本和可用功能"

了解功能可用性：

PostgreSQL 16 - 17：所有功能可用。
PostgreSQL 15+：单独的检查点器统计信息。
PostgreSQL 14+：并行查询跟踪。
PostgreSQL 12 - 13：仅核心功能。

如果工具显示 “不可用”：

该功能需要较新的PostgreSQL版本。
工具将自动使用最佳可用替代方案。
考虑升级PostgreSQL以获得增强的监控功能。

🔧 技术细节

测试与开发

# 使用MCP检查器进行测试
./scripts/run-mcp-inspector-local.sh

# 直接执行以进行调试
python -m src.mcp_postgresql_ops.mcp_main --log-level DEBUG

# 测试版本兼容性（需要不同的PostgreSQL版本）
# 修改.env中的POSTGRES_HOST以指向不同版本

# 运行测试（如果有）
uv run pytest

版本兼容性测试

MCP服务器可自动适应PostgreSQL 12 - 17版本。要跨版本进行测试：

设置测试数据库：使用不同的PostgreSQL版本（12、14、15、16、17）。
运行兼容性测试：指向每个版本并验证工具行为。
检查功能检测：确保正确检测版本和功能可用性。
验证回退行为：确认在较旧版本上的优雅降级。

安全说明

所有工具均为只读 - 无数据修改功能。
输出中会屏蔽敏感信息（如密码）。
不直接执行SQL - 仅使用预定义查询。
遵循最小权限原则。

📄 许可证

本项目遵循 MIT许可证，您可以自由使用、修改和分发。

⭐ 其他项目

由同一作者开发的其他MCP服务器：

🤝 贡献

我们始终欢迎新的贡献者！无论您是修复拼写错误、添加新的监控工具还是改进文档，每一份贡献都将使这个项目变得更好。

贡献方式：

🐛 报告问题或漏洞。
💡 提出新的PostgreSQL监控功能建议。
📝 改进文档。
🚀 提交拉取请求。
⭐ 如果您觉得这个项目有用，请给它加星！

💡 使用建议

代码库的设计非常便于添加新工具。请查看 mcp_main.py 中现有的 @mcp.tool() 函数。

MCPO Swagger文档

[MCPO Swagger URL] http://localhost:8003/postgresql-ops/docs

0 条评论
分类：数据库

Mcp Postgresql Ops

🚀 PostgreSQL操作与监控MCP服务器

✨ 主要特性

🔧 高级功能

🚀 快速开始

1. 环境设置

2. 启动演示容器

3. 访问OpenWebUI

4. 在OpenWebUI中注册工具

5. 完成！

🚀 尝试以下示例查询：

💻 使用示例

Claude桌面集成

独立运行MCP服务器

使用Pypi和uvx（推荐）

（可选）配置多个PostgreSQL实例

使用本地源代码

📚 详细文档

环境变量

先决条件

所需的PostgreSQL扩展

最低要求

所需的PostgreSQL配置

方法1：postgresql.conf（适用于自管理的PostgreSQL，推荐）

方法2：PostgreSQL启动参数

方法3：动态配置（适用于AWS RDS、Azure、GCP等托管服务）

RDS/Aurora兼容性

示例查询

🟢 无需扩展的工具（始终可用）

🚀 版本感知工具（自动适应）

🟡 需要扩展的工具

工具兼容性矩阵

🟢 无需扩展的工具（始终可用）

🚀 版本感知工具（自动适应）

🟡 需要扩展的工具

故障排除

连接问题

扩展错误

配置问题

性能问题

版本兼容性问题

🔧 技术细节

测试与开发

版本兼容性测试

安全说明

📄 许可证

⭐ 其他项目

🤝 贡献

MCPO Swagger文档

0 个评论

相似服务问题

相关AI产品

热议话题 »