DBeast PostgreSQL MCP

---

DBeast 通过 Model Context Protocol 将 Claude、Cursor、Windsurf 和 VS Code Copilot 等 AI 助手连接到 PostgreSQL。DBeast 不会暴露一个宽泛的 execute_sql 逃生口，而是提供 21 个专用工具，用于发现架构、安全执行查询、影响分析、性能审查、安全检查、维护报告、复制监控和数据质量检查。

---

演示

观看 Claude 使用 DBeast MCP 工具审计 PostgreSQL 数据库、识别安全和维护风险，并在不执行破坏性 SQL 的情况下预览清理影响。

---

工作原理

AI assistant  --MCP stdio-->  DBeast server  --asyncpg-->  PostgreSQL
Claude/Cursor                  Python local                 Local, RDS,
Windsurf/VS Code               subprocess                   Supabase, Neon

DBeast 作为本地 stdio MCP 服务运行。你的 IDE 或桌面助手会将其作为子进程启动，并通过环境变量传递数据库凭据。助手调用 DBeast 工具，DBeast 查询 PostgreSQL，然后将结构化结果返回给助手。无需 HTTP 服务或额外基础设施。

---

快速开始

1. 安装

git clone https://github.com/snss10/DBeast.git
cd DBeast
pip install -e .

用于开发：

pip install -e ".[dev]"

可选：将 .env.example 复制为 .env 并设置数据库凭据。

2. 验证

dbeast

或者直接运行源代码入口：

python src/server.py

3. 配置 MCP 客户端

Cursor 或 Windsurf 的最简配置：

{
  "mcpServers": {
    "dbeast": {
      "type": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/DBeast/src/server.py"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

常见配置位置：

客户端	配置位置
Cursor	项目根目录中的 .mcp.json，或全局配置 ~/.cursor/.mcp.json
VS Code	.vscode/settings.json，或用户设置中的 mcp.servers 键
macOS 上的 Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Windows 上的 Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json
Windsurf	.mcp.json

有关客户端完整示例、Docker、RDS、Supabase、Neon、SSH 隧道、AWS Secrets Manager 和故障排除，请参阅 SETUP.md。

4. 提出简单或复杂的问题

连接后，你的助手既能回答快速查询问题，也能执行多步骤数据库调查。

简单示例：

Show me the schema for the orders table.
Which queries are slowest right now?
Run a security audit on the public schema.
Generate a Mermaid ERD for the sales schema.

更复杂的示例：

Before I archive old sessions, estimate how many rows would be affected, identify related tables, and tell me the rollback risk.
Investigate why the dashboard query is slow, explain the execution plan, and suggest safe indexes.
Review the public schema for maintenance issues, security risks, and data quality problems, then summarize the top priorities.
Compare table growth, dead tuples, and index health across all schemas and recommend what to vacuum or reindex first.

---

工具

DBeast 提供 10 个类别共 21 个 MCP 工具。

连接

工具	说明
connect	连接到 PostgreSQL、检查当前状态或发现本地数据库
disconnect	关闭当前数据库连接
health_check	验证连接、连接池健康状况、PostgreSQL 版本和扩展

架构发现

工具	说明
get_schema	列出架构、表、列、索引、关系，以及可选的 Mermaid ERD
dependency_analysis	在重命名、删除或更改数据库对象之前映射对象依赖关系

数据访问

工具	说明
execute_query	运行只读 SELECT 查询，并自动注入行数限制

查询分析

工具	描述
analyze_query	解析并检查查询结构、警告和优化提示
query_optimizer	针对给定查询推荐索引和重写方案
analyze_impact	在不执行写入查询的情况下，预览其影响、风险级别、受影响的行和回滚上下文

数据库健康状况

工具	描述
database_health	检查缓存命中率、连接、事务时长、表健康状况和整体健康信号
query_performance	根据 PostgreSQL 统计信息报告缓慢或开销较大的查询

安全性

工具	描述
security_audit	检查角色、权限、超级用户帐户和 public 模式的暴露情况
sensitive_data_scan	根据列名和模式特征检测可能的个人身份信息或机密

维护

工具	描述
maintenance_analysis	检查 vacuum 状态、死元组、分析时间戳和索引健康状况
partition_analysis	检查分区健康状况、行分布和缺少分区的风险

数据质量

工具	描述
data_quality_report	分析空值率、基数、值分布和异常值
duplicate_detection	查找所选键列中的重复行

服务配置

工具	描述
configuration_review	检查 PostgreSQL 配置和调优机会
replication_status	检查复制延迟、WAL 发送器/接收器状态和复制槽

审计

工具	描述
get_audit_logs	获取指定日期记录的 MCP 工具调用
list_audit_files	列出可用的审计日志文件

---

推荐工作流

首先发现架构：

get_schema()
get_schema(schema='public')

运行安全的只读查询：

execute_query(query='SELECT * FROM orders ORDER BY created_at DESC')

预览有风险的写入操作：

analyze_impact(query='DELETE FROM sessions WHERE last_active < now() - interval ''30 days''')

检查健康状况和维护情况：

database_health()
maintenance_analysis(schema='public')
query_performance()

大多数分析工具都接受 schema 参数：

maintenance_analysis(schema='public')  -> analyze one schema
maintenance_analysis(schema='all')     -> analyze every schema
get_schema(format='mermaid')           -> generate an ERD diagram

---

支持的数据库

提供商	连接方式
本地 PostgreSQL	DATABASE_URL 或单独的 DB_* 变量
Docker PostgreSQL	显式变量或 connect(discover=true)
AWS RDS / Aurora	直接 URL、SSH 隧道或 AWS Secrets Manager
Supabase	从 Dashboard 设置获取连接池连接字符串
Neon	从 Console 连接详情获取连接字符串
Railway / Render / Fly.io	提供商连接字符串
任意 PostgreSQL 主机	标准 PostgreSQL URL

---

配置

选择一种连接方式。

# Full URL
DATABASE_URL=postgresql://user:pass@host:5432/db

# Or individual variables
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASSWORD=secret
DB_NAME=mydb
DB_SSLMODE=prefer

# Or AWS Secrets Manager
AWS_SECRET_NAME=my-rds-secret
AWS_REGION=us-west-2

你也可以在运行时连接：

connect(url='postgresql://user:pass@host:5432/db')
connect(host='localhost', user='postgres', password='secret', database='mydb')
connect(aws_secret_name='my-secret', aws_region='us-west-2')

关键设置：

变量	默认值	描述
DBEAST_DEFAULT_ROW_LIMIT	100	execute_query 返回的最大行数
DBEAST_QUERY_TIMEOUT	300	查询执行超时时间，单位为秒
DBEAST_COMMAND_TIMEOUT	300	SQL 命令超时时间，单位为秒
DBEAST_SSL_VERIFY	true	对于证书与 localhost 不匹配的 SSH 隧道，设为 false
DBEAST_SCHEMA_CACHE_TTL	60	架构缓存 TTL，单位为秒；0 表示禁用缓存
DBEAST_AUDIT_ENABLED	true	记录 MCP 工具调用
DBEAST_AUDIT_DIR	logs/mcp_audit	审计日志目录

完整配置参考请参阅 SETUP.md。

---

安全模型

查询类型	DBeast 的处理方式
SELECT	自动限制行数后执行
INSERT / UPDATE / DELETE	从不执行；返回影响预览
DROP / TRUNCATE	从不执行；报告受影响的对象和风险

格式化响应和 JSON 响应使用一致的封装格式：

{
  "success": true,
  "data": { "...": "..." },
  "meta": {
    "connected": true,
    "source": "tool"
  }
}

---

审计日志记录

DBeast 会记录 MCP 工具调用，以便追责和调试。

DBEAST_AUDIT_ENABLED=true
DBEAST_AUDIT_DIR=logs/mcp_audit

审计文件按天存储为 Markdown 文件，其中包含时间戳、工具名称、耗时、脱敏后的参数、截断后的响应和错误。

---

开发

pip install -e ".[dev]"
pre-commit install
pytest tests/ -v
ruff check src/ tests/
ruff format src/ tests/

启动可选的本地 PostgreSQL 测试数据库：

docker compose up -d postgres

旧版 Compose：

docker-compose up -d postgres

---

文档

• SETUP.md - 完整的客户端设置、连接场景、配置和故障排除
• CONTRIBUTING.md - 开发环境设置、测试、代码风格、提交和 PR 流程
• CODE_OF_CONDUCT.md - 社区准则

---

许可证

MIT