universal-db-mcp

通用数据库 MCP 服务

面向 AI Agent 数据库访问、以安全为先的 Python 原生 MCP 服务。

---

为什么要构建它

大多数数据库 MCP 服务都会向 AI Agent 提供原始 SQL 访问权限，然后听天由命。 本服务将大模型视为不可信输入，并在任何查询到达数据库之前应用 8 层注入防护——包括拦截 UNION 攻击、 堆叠语句、基于时间的注入和注释绕过。

支持：PostgreSQL · SQLite · MySQL · DuckDB（列式分析）

---

零配置：现在就能在笔记本电脑上运行

无需 Docker，无需云账户，也无需安装数据库服务端。DuckDB 和 SQLite 在进程内运行：

# Query a local SQLite database — one command, zero infra
SQLITE_PATH=./myapp.db uvx universal-db-mcp

# Query a local DuckDB file or parquet files
DUCKDB_PATH=./analytics.duckdb uvx universal-db-mcp

# In-memory DuckDB for throwaway analysis
DUCKDB_PATH=:memory: uvx universal-db-mcp

添加到 Claude Code 的 ~/.claude/mcp_servers.json，或添加到 Claude Desktop 的 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS） / %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "mydb": {
      "command": "uvx",
      "args": ["universal-db-mcp"],
      "env": {
        "SQLITE_PATH": "/Users/you/projects/myapp/db.sqlite3",
        "ALLOW_DESTRUCTIVE": "false"
      }
    }
  }
}

保存后重启 Claude Desktop / Claude Code——就这么简单。

Claude Code 会自动发现这些工具。

更多客户端配置（Claude Desktop、Cursor、Windsurf、Docker）见 examples/。

---

安全模型：8 层

默认只读。纵深防御。每个查询在接触驱动程序之前都会经过验证。

层级	功能
1	驱动程序级只读 — PostgreSQL 会话标志、SQLite mode=ro URI、DuckDB read_only=True。写操作会在 SQL 解析前被拒绝。
2	关键字拦截 — 只读模式下拦截 DROP、DELETE、TRUNCATE、ALTER、INSERT、UPDATE、GRANT、EXEC
3	注入模式检测 — UNION SELECT、堆叠语句、SQL 注释（--、/*）、xp_、SLEEP()、WAITFOR、BENCHMARK()
4	拒绝多条语句 — 始终拦截用于分隔语句的 ;
5	参数类型强制 — 参数仅接受 str、int、float、bool、null
6	结果大小限制 — 截断至 MAX_RESULT_ROWS（默认 1000），防止内存耗尽
7	标识符清理 — 在内部生成的 SQL 中剔除表名/列名中的元字符
8	DuckDB 文件系统拦截列表 — 在适配器层拦截 read_csv()、read_parquet()、glob()、LOAD、INSTALL、httpfs、COPY；read_only=True 只会拦截写操作，不会拦截文件读取

完整威胁模型：docs/SECURITY.md

---

DuckDB：无需基础设施的分析

DuckDB 在进程内运行（无需服务端），并原生读取 Parquet、CSV、JSON。 无需搭建数据仓库，即可将 AI Agent 连接到分析数据：

# Query parquet files directly
DUCKDB_PATH=:memory: uvx universal-db-mcp

然后在 Claude Code 中：

You: "Load sales.parquet and show me monthly revenue by region"
Claude: [uses query tool → SELECT region, strftime('%Y-%m', date) AS month, SUM(revenue) ...]

---

自然语言 → SQL

无需单独的自然语言转 SQL 工具——Claude 已能完成此操作。提供 schema 工具并用普通英语提问：

You: "Which customers placed more than 5 orders last month?"
Claude: [calls schema() to see table structure, then query() with the
         generated SQL — every query still passes through all 8 security
         layers before touching your database]

原型开发时可配合 dry_run: true（DRYRUN=true）使用——Claude 会返回 查询计划，但不会执行任何操作。

---

Docker

docker build -t universal-db-mcp .
docker run -i --rm \
  -e POSTGRES_URI=postgresql://readonly:[email protected]:5432/mydb \
  -e ALLOW_DESTRUCTIVE=false \
  universal-db-mcp

如何将其接入 MCP 客户端，请参阅 examples/docker_mcp_config.json。

---

所有数据库

# PostgreSQL
POSTGRES_URI=postgresql://readonly:pass@localhost/mydb uvx universal-db-mcp

# SQLite (local file, zero infra)
SQLITE_PATH=./db.sqlite3 uvx universal-db-mcp

# MySQL
MYSQL_URI=mysql://readonly:pass@localhost/mydb uvx universal-db-mcp

# DuckDB (columnar, in-process analytics)
DUCKDB_PATH=./analytics.duckdb uvx universal-db-mcp

# Multiple databases simultaneously
POSTGRES_URI=... SQLITE_PATH=... uvx universal-db-mcp

---

MCP 工具

工具	描述
query	执行 SQL——默认只读，并应用全部 8 层安全防护
schema	检查表和列——无需配置
explain	获取查询执行计划，但不运行查询
health	检查连接状态、数据库版本和连接池指标
list_databases	显示所有已配置的数据库及连接状态
query_history	查看最近执行的 100 条查询
snapshot_schema	捕获当前架构，用于检测架构变更
schema_diff	将当前架构与上次快照进行比较

v1.1.0：新增试运行模式（DRYRUN=true）、表允许列表（WHITELISTED_TABLES）、查询复杂度警告、结构化审计日志，以及用于验证连通性的 --check CLI 标志。详见 CHANGELOG.md。

---

配置

# ── PostgreSQL ─────────────────────────────────────
POSTGRES_URI=postgresql://user:pass@host:5432/db
POSTGRES_READONLY=true          # default: true

# ── SQLite ─────────────────────────────────────────
SQLITE_PATH=/path/to/database.db
SQLITE_READONLY=true            # default: true

# ── MySQL ──────────────────────────────────────────
MYSQL_URI=mysql://user:pass@host:3306/db
MYSQL_READONLY=true             # default: true

# ── DuckDB ─────────────────────────────────────────
DUCKDB_PATH=/path/to/analytics.duckdb   # or :memory:
DUCKDB_READONLY=true            # default: true

# ── Security ───────────────────────────────────────
ALLOW_DESTRUCTIVE=false         # default: false — blocks INSERT/UPDATE/DELETE/DROP
MAX_RESULT_ROWS=1000            # truncate large results
ENABLE_LOGGING=true             # log queries to stderr
QUERY_TIMEOUT=30                # seconds
RATE_LIMIT_RPM=60               # requests per minute

---

安全的数据库用户

始终使用专用的只读账号。切勿向 MCP 服务提供可修改数据的凭据。

PostgreSQL：

CREATE USER mcp_agent WITH PASSWORD 'strong_random_password';
GRANT CONNECT ON DATABASE mydb TO mcp_agent;
GRANT USAGE ON SCHEMA public TO mcp_agent;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_agent;

MySQL：

CREATE USER 'mcp_agent'@'localhost' IDENTIFIED BY 'strong_random_password';
GRANT SELECT ON mydb.* TO 'mcp_agent'@'localhost';
FLUSH PRIVILEGES;

---

开发

git clone <repo-url>
cd universal-db-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# Run tests (67+ passing, no external DB required for SQLite + DuckDB)
pytest

# Security tests only
pytest tests/test_security.py -v

# With coverage
pytest --cov=src/universal_db_mcp --cov-report=term-missing

---

架构

src/universal_db_mcp/
├── server.py          # FastMCP server — 5 tools
├── config.py          # Env-var config via Pydantic
├── adapters/
│   ├── base.py        # Abstract adapter + result dataclasses
│   ├── postgresql.py  # asyncpg, connection pool, read-only via init callback
│   ├── sqlite.py      # aiosqlite, read-only via file URI mode=ro
│   ├── mysql.py       # aiomysql, DictCursor
│   └── duckdb.py      # duckdb, thread-pool executor, lock-guarded
└── security/
    └── sanitizer.py   # SQLSanitizer — 8-layer injection prevention

docs/
└── SECURITY.md        # Full security architecture and threat model

---

与 Google MCP Toolbox 对比

	本项目	Google MCP Toolbox
运行环境	Python——pip install / uvx	Go 二进制文件 / Docker
本地数据库	SQLite + DuckDB，无需基础设施	不支持 SQLite
分析	进程内 DuckDB	无列式适配器
身份验证模型	默认只读 + 环境变量	IAM / 原生 GCP
SQL 注入	8 层清理器 + 参数化查询	侧重身份验证
扩展	Python 生态，可使用任意 pip 包	Go 插件
供应商	中立	Google Cloud 导流

不同的工具适用于不同的任务。如果你希望使用原生 Python、优先本地部署且经过安全加固的访问方式，同时不依赖云服务，请使用本项目。

---

许可证

MIT — LICENSE

---

安全声明：此服务为 AI Agent 提供数据库访问权限。始终使用只读凭据，在生产部署前查看 docs/SECURITY.md，并且切勿提交 .env 文件。