Db Whisper
Description
# 🛡️ DB-Whisper (Production-Hardened MCP Server) [中文] | [English] **DB-Whisper** 是一个基于 Anthropic **Model Context Protocol (MCP)** 的生产级数据库只读访问工具。它专为 AI 助手（如 Cursor, Claude Desktop）设计，提供严苛的安全边界和深度 AST 校验，确保 AI 只能在受控环境下安全地查询并理解你的数据库。 A production-grade, AST-hardened database…
About
# 🛡️ DB-Whisper (Production-Hardened MCP Server) [中文] | [English] **DB-Whisper** 是一个基于 Anthropic **Model Context Protocol (MCP)** 的生产级数据库只读访问工具。它专为 AI 助手（如 Cursor, Claude Desktop）设计，提供严苛的安全边界和深度 AST 校验，确保 AI 只能在受控环境下安全地查询并理解你的数据库。 A production-grade, AST-hardened database inspection tool based on the **Model Context…
Details
- Author
- 404-UNKNOW
- GitHub stars
- 1
- Downloads
- 440
- Categories
- Database, Developer Tools
Jump to
- Deep AST firewall with strict whitelist and default-deny policy.
- Isolation from system metadata tables (e.g., information_schema, pg_catalog, sqlite_schema).
- Complexity limits: AST nodes ≤150, nesting depth ≤8.
- Driver-level read-only enforcement for SQLite and PostgreSQL.
- Rate limiting: default 10 queries per minute via token bucket.
- Zero‑information leakage on security blocks; audit masking for sensitive data.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Db WhisperCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Db Whisper is invoked via npx -y db-whisper-mcp and configured through environment variables such as DATABASE_URL, ALLOWED_TABLES, DB_SSL, and QUERY_TIMEOUT_MS. Integration with Claude Desktop or Cursor requires adding a JSON configuration block under mcpServers with the appropriate command, args, and env.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"db whisper": {
"db-whisper": {
"command": "npx",
"args": [
"-y",
"db-whisper-mcp"
],
"env": {
"DATABASE_URL": "postgresql://username:password@host:port/database",
"NODE_ENV": "production"
}
}
}
}
}McpServers
{
"db-whisper": {
"command": "npx",
"args": [
"-y",
"db-whisper-mcp"
],
"env": {
"DATABASE_URL": "postgresql://username:password@host:port/database",
"NODE_ENV": "production"
}
}
}🛡️ DB-Whisper (Production-Hardened MCP Server)
[中文] | [English]
DB-Whisper 是一个基于 Anthropic Model Context Protocol (MCP) 的生产级数据库只读访问工具。它专为 AI 助手（如 Cursor, Claude Desktop）设计，提供严苛的安全边界和深度 AST 校验，确保 AI 只能在受控环境下安全地查询并理解你的数据库。
A production-grade, AST-hardened database inspection tool based on the Model Context Protocol (MCP). Designed for AI assistants (Cursor, Claude Desktop), providing strict security boundaries to ensure AI can safely query and understand your database in a read-only, controlled environment.
---
🌟 核心安全性 / Core Security (Production-Ready)
1. 深度 AST 防火墙 (Deep AST Firewall)
- 🛡️ 严格白名单 (Strict Whitelist): 采用 Default Deny 策略，仅允许必要的 SELECT 节点类型。 - 🚫 系统表隔离 (System Metadata Isolation): 彻底封堵对information_schema, pg_catalog 以及 SQLite 3.33.0+ 别名（如 sqlite_schema, sqlite_temp_schema）的访问。
- 🧩 复杂度限制 (Complexity Limits): 限制 AST 节点数 (≤150) 与嵌套深度 (≤8)，防止通过超大规模 SQL 进行资源耗尽攻击。
2. 驱动级只读保障 (Driver-Level Read-Only)
- 🗄️ SQLite 强制只读: 启用readonly: true 模式并强制 PRAGMA query_only = ON。
- 🐘 PostgreSQL 事务保障: 每一条查询均在 BEGIN READ ONLY 事务中执行，确保数据库层面无法写入。
- 🔒 SSL 安全加固: 默认启用 rejectUnauthorized: true，防止中间人攻击。
3. 运行限流与脱敏 (Rate Limiting & Masking)
- ⏱️ 令牌桶限流 (Rate Limiting): 默认限制为 10 次查询/分钟，防止 AI 滥用导致数据库负载过高。 - 🤫 零信息泄露 (Zero Leakage): 安全拦截均返回通用错误信息，不泄露表名、列名等具体元数据。 - 🕵️ 审计脱敏 (Audit Masking): 自动识别并脱敏日志中的密码、API Key、邮箱及信用卡号。---
🚀 快速上手 / Quick Start
1. 配置建议 / Mandatory Setup (Least Privilege)
重要安全提示：请务必为 MCP 创建专用的 只读数据库用户，并配合环境变量进行权限细化。 Critical: Always use a dedicated Read-Only DB User.2. 环境变量配置 / Environment Variables
| 变量 | 说明 | 默认值 | |---|---|---| |DATABASE_URL | 数据库连接串 (Postgres URI 或 SQLite 绝对路径) | (必填) |
| ALLOWED_TABLES | 表名白名单，用逗号分隔 (如 users,orders) | * (仅黑名单模式) |
| DB_SSL | 是否强制启用 SSL 验证 | false |
| QUERY_TIMEOUT_MS | 单次查询硬超时时间 | 10000 |
3. 在 Claude Desktop / Cursor 中集成
{
"mcpServers": {
"db-whisper": {
"command": "npx",
"args": ["-y", "db-whisper-mcp"],
"env": {
"DATABASE_URL": "postgresql://user:pass@localhost:5432/db",
"ALLOWED_TABLES": "public_users,products",
"NODE_ENV": "production"
}
}
}
}
---
🛠️ 工程化支持 / Engineering & QA
- 自动化测试: 已通过 vitest 实现 100% 对抗性安全测试，覆盖 SQLite 别名绕过、嵌套 DML 拦截及限流逻辑。
- 依赖安全: 所有关键依赖已升级至最新版，并通过 npm audit 验证。
npm install # 安装依赖
npm test # 运行安全与限流测试 (需 DATABASE_URL 环境)
npm run build # 编译项目
---
🔗 相关资源 / Resources
- SECURITY.md: 详细的安全政策与加固指南。 - CONTEXT.md: 项目演进记录与重要约定。---
Note: All logs are directed to stderr; stdout is reserved strictly for MCP protocol data.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
