MCP-PostgreSQL-Ops：用于PostgreSQL数据库运维和监控的工具

MCP-PostgreSQL-Ops 是一个为PostgreSQL数据库设计的专业运维与监控工具。它通过一个安全的模型上下文协议（MCP）服务器，为大型语言模型（LLM）或AI代理提供与数据库交互的能力。这个工具最大的特点是所有操作均为只读，确保了在进行性能分析、配置检查和结构浏览时，不会对线上数据库造成任何意外的修改，保障了数据的绝对安全。该项目利用 PostgreSQL 内置的 pg_stat_statements 和 pg_stat_monitor 扩展插件，提供了深度的性能洞察能力，可以帮助数据库管理员（DBA）和开发人员快速定位慢查询、分析索引使用效率以及管理数据库容量。用户可以通过自然语言提问的方式来执行各种运维指令，例如“查询最慢的10条SQL”或“检查数据库的连接数”，让复杂的数据库管理工作变得更加简单和直观。

功能列表

• 服务器信息与状态:
  • get_server_info: 获取PostgreSQL服务器版本、运行状态以及已安装的扩展插件信息。
  • get_active_connections: 查看当前数据库的活跃连接数和会话详情。
  • get_postgresql_config: 根据关键字搜索并获取PostgreSQL的配置参数。
• 数据库结构浏览:
  • get_database_list: 列出所有的数据库及其大小。
  • get_table_list: 展示指定数据库中的所有表和它们的大小信息。
  • get_user_list: 列出数据库的所有用户及其权限。
• 性能监控与分析:
  • get_pg_stat_statements_top_queries: 基于性能统计数据，分析并找出执行缓慢的查询（慢查询）。
  • get_pg_stat_monitor_recent_queries: 实时监控最近执行的查询。
  • get_index_usage_stats: 分析索引的使用频率和效率，帮助识别未使用或低效的索引。
• 容量管理:
  • get_database_size_info: 分析并展示每个数据库的容量大小。
  • get_table_size_info: 分析并展示数据表和索引的大小。
  • get_vacuum_analyze_stats: 查看数据库表的VACUUM（垃圾回收）和ANALYZE（统计信息更新）的状态与历史记录。

使用帮助

MCP-PostgreSQL-Ops的安装和使用流程非常直接，主要分为环境准备、安装依赖和启动服务三个步骤。

第一步：环境准备与配置

在开始之前，你需要确保系统已经安装了Python 3.11或更高版本，以及uv这个Python包管理工具。

1. 下载项目代码
   首先，从GitHub克隆项目到你的本地电脑。

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

2. 配置数据库连接
   项目中包含一个名为.env.example的配置文件模板。你需要复制这个文件并重命名为.env，然后根据你的实际情况修改里面的数据库连接信息。

   cp .env.example .env
   

   接下来，使用文本编辑器打开.env文件，填入你的PostgreSQL数据库信息：

   # 数据库服务器的主机名或IP地址
   POSTGRES_HOST=localhost
   # 数据库服务器的端口
   POSTGRES_PORT=5432
   # 连接数据库的用户名
   POSTGRES_USER=postgres
   # 连接数据库的密码
   POSTGRES_PASSWORD=your-secret-password
   # 默认连接的数据库名称
   POSTGRES_DB=postgres
   

第二步：安装必需的PostgreSQL扩展

为了使用完整的性能监控功能，你的PostgreSQL数据库必须启用pg_stat_statements扩展。这是一个官方扩展，通常默认安装但未启用。

1. 修改postgresql.conf
   找到你的PostgreSQL配置文件postgresql.conf，在shared_preload_libraries配置项中添加pg_stat_statements。

   shared_preload_libraries = 'pg_stat_statements'
   

   如果你还想使用实时查询监控功能，可以一并添加pg_stat_monitor。

   shared_preload_libraries = 'pg_stat_statements,pg_stat_monitor'
   

2. 重启数据库服务
   修改配置后，必须重启PostgreSQL服务才能生效。
3. 在数据库中创建扩展
   使用数据库客户端（如psql）连接到你的数据库，然后执行以下SQL命令来创建扩展。

   CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
   -- 如果需要，也创建pg_stat_monitor
   CREATE EXTENSION IF NOT EXISTS pg_stat_monitor;
   

   你可以通过项目提供的get_server_info工具来验证扩展是否安装成功。

第三步：安装Python依赖并启动服务

1. 创建虚拟环境并安装依赖
   项目推荐使用uv来管理Python环境和依赖，它可以非常快速地完成安装。

   # 创建一个基于Python 3.11的虚拟环境
   uv venv --python 3.11
   # 激活虚拟环境 (在Linux/macOS下)
   source .venv/bin/activate
   # 安装所有依赖
   uv sync
   

2. 启动MCP服务
   项目提供了多种启动方式，最常用的是在本地进行开发和测试的模式。
   • 开发模式（推荐）
     直接运行脚本，此模式会启动一个本地的MCP检查器，方便你直接与工具交互。

     ./scripts/run-mcp-inspector-local.sh
     

   • 调试模式
     如果你需要看到更详细的日志输出，可以直接用Python命令启动，并设置日志级别为DEBUG。

     python -m src.mcp_postgresql_ops.mcp_main --log-level DEBUG
     

   • HTTP服务模式
     你也可以将服务作为HTTP服务器来运行，这样其他的应用程序就可以通过网络请求来调用它的功能。

     python -m src.mcp_postgresql_ops.mcp_main \
     --type streamable-http \
     --host 127.0.0.1 \
     --port 8080 \
     --log-level DEBUG
     

     服务启动后，你就可以通过AI代理或者其他MCP客户端与其进行交互，发送自然语言指令来管理和监控你的数据库了。例如，你可以提问：“显示前10名最慢的查询”或者“检查所有数据库的大小”。

应用场景

1. 数据库性能瓶颈定位
   当线上应用出现响应缓慢时，DBA或开发人员可以立即使用此工具查询当前数据库的性能状况。通过提问“分析一下最耗费资源的SQL查询”或“显示最近的慢查询”，可以快速定位到导致性能问题的具体SQL语句，从而进行针对性优化，而不用担心任何误操作影响生产环境。
2. 日常数据库健康巡检
   DBA可以每天使用此工具进行例行检查。通过查询“当前有多少活跃连接？”、“检查所有数据库的大小”和“哪些表需要执行VACUUM？”，可以全面了解数据库的运行状态、容量使用情况和维护需求，实现主动式运维，防患于未然。
3. AI代理集成与自动化运维
   可以将此工具集成到AI代理或自动化运维流程中。例如，设定一个自动化任务，让AI代理每天定时查询“检查一下有没有未使用的索引”，如果发现无用索引，则自动生成报告或告警，帮助DBA持续优化数据库结构，降低维护成本。
4. 数据架构和资源规划
   在进行系统架构设计或容量规划时，开发和运维团队可以利用此工具了解现有数据库的结构和资源使用情况。通过查询“列出所有表和索引的大小”、“查看用户的权限列表”，可以为新功能的开发和未来的服务器资源采购提供准确的数据支持。

QA

1. 这个工具会修改我的数据库吗？
   绝对不会。MCP-PostgreSQL-Ops最核心的设计原则之一就是安全，所有的操作都是只读的。它仅查询数据库的系统目录和性能统计视图，不会执行任何UPDATE、DELETE或INSERT等写操作，可以放心在生产环境中使用。
2. 使用这个工具前，我需要为数据库做什么准备？
   你需要确保数据库版本为PostgreSQL 12或更高。最重要的准备工作是启用pg_stat_statements扩展，因为它是性能分析功能的基础。启用它需要修改postgresql.conf文件并重启数据库服务，具体步骤已在“使用帮助”部分详细说明。
3. 什么是MCP？这个工具有什么不同？
   MCP（Model Context Protocol）是一种让AI模型能够安全地与外部工具（如数据库）交互的协议。它定义了一套规则，让AI知道这个工具有哪些功能、如何调用。与其他可能允许AI直接执行SQL查询的工具不同，本工具将所有操作封装成安全的、预定义好的只读功能，AI只能调用这些功能，而不能执行任意代码，从而避免了SQL注入等安全风险。
4. 我可以在多台数据库服务器上使用这个工具吗？
   可以。你只需要修改.env配置文件中的数据库连接信息，指向不同的数据库服务器，然后重启服务即可。如果你希望同时监控多台服务器，可以为每台服务器启动一个独立的MCP-PostgreSQL-Ops服务实例。