DatabaseAItool

给第三方 AI Agent 使用的只读数据库 MCP 工具，附带本地管理界面。

• 多数据库：MySQL / MariaDB、PostgreSQL、SQLite、SQL Server、Oracle、MongoDB

• 管理界面：维护数据库连接、测试连接、创建/编辑/禁用/重置 API Key

• 按 Key 授权：每个 Key 只能访问被勾选的数据库

• 本地存储：连接信息保存在本机 SQLite，数据库密码使用 Fernet 加密，Key 只保存 HMAC 哈希

• 只读保证：工具只提供读取能力，SQL 白名单校验 + 数据库层只读 + 行数/超时限制

• MCP 传输：HTTP Streamable（/mcp，Bearer Key）与 stdio（MCP_API_KEY 环境变量）

设计上不提供任何写入、DDL、建库/建表/改字段、删除数据的能力。

快速开始

方式一：Docker（推荐）

需要 Docker 20.10+。镜像已包含 SQL Server 的 ODBC Driver 18；Oracle 使用 thin 模式，无需安装数据库客户端。

# 1. 构建镜像
docker build -t database-ai-tool .

# 2. 启动容器（数据持久化，仅本机可访问）
docker run -d --name database-ai-tool \
  --restart unless-stopped \
  -p 127.0.0.1:8000:8000 \
  -v database-ai-tool-data:/data \
  -e ADMIN_PASSWORD='换成你的强密码' \
  database-ai-tool

# 3. 检查状态
docker ps
docker logs -f database-ai-tool
curl http://127.0.0.1:8000/healthz

打开 http://127.0.0.1:8000，用户名 admin，密码为启动时设置的 ADMIN_PASSWORD。

局域网 / 远程访问（必须设置密码，并配置客户端实际使用的 Host）：

docker run -d --name database-ai-tool \
  --restart unless-stopped \
  -p 8000:8000 \
  -v database-ai-tool-data:/data \
  -e ADMIN_PASSWORD='换成你的强密码' \
  -e MCP_ALLOWED_HOSTS='192.168.1.10:8000,dbtool.example.com' \
  database-ai-tool

• MCP_ALLOWED_HOSTS 要填写 MCP 客户端访问时 Host 头的值（IP/域名，带端口），否则 MCP 会返回 421 Invalid Host header。

• 生产环境请放在 HTTPS 反向代理之后，不要把端口直接暴露到公网。

docker compose（保存为 docker-compose.yml，执行 docker compose up -d）：

services:
  database-ai-tool:
    build: .
    container_name: database-ai-tool
    restart: unless-stopped
    ports:
      - "127.0.0.1:8000:8000"
    environment:
      ADMIN_PASSWORD: "换成你的强密码"
      # MCP_ALLOWED_HOSTS: "192.168.1.10:8000"
      DEFAULT_MAX_ROWS: "500"
      HARD_MAX_ROWS: "5000"
    volumes:
      - database-ai-tool-data:/data

volumes:
  database-ai-tool-data:

容器内监听 0.0.0.0:8000，能否被外部访问由 -p 的绑定地址决定；-p 127.0.0.1:8000:8000 只允许本机访问。

构建失败：Temporary failure resolving 'deb.debian.org'

这是 Docker 构建环境无法解析域名，与项目代码无关。按顺序排查：

1. 确认容器 DNS 是否正常：

   docker run --rm busybox nslookup deb.debian.org

   解析失败时，在 Docker Desktop → Settings → Docker Engine 中加入公共 DNS，保存并重启 Docker：

   {
     "dns": ["223.5.5.5", "119.29.29.29"]
   }

   Linux 服务器可将同样内容写入 /etc/docker/daemon.json，然后执行 sudo systemctl restart docker。

2. 仍失败时，改用国内 Debian 镜像源构建：

   docker build \
     --build-arg APT_MIRROR=mirrors.huaweicloud.com \
     -t database-ai-tool .

   APT_MIRROR 也可换成 mirrors.aliyun.com、mirrors.tuna.tsinghua.edu.cn、mirrors.ustc.edu.cn、mirrors.cloud.tencent.com；可用 docker run --rm busybox nslookup mirrors.huaweicloud.com 先确认能解析。

3. 公司网络需要代理时，在 Docker Desktop 中配置代理，或构建时传入：

   docker build \
     --build-arg HTTP_PROXY=http://代理地址:端口 \
     --build-arg HTTPS_PROXY=http://代理地址:端口 \
     -t database-ai-tool .

4. 只使用 MySQL / PostgreSQL / SQLite / Oracle / MongoDB 时，可以跳过 Microsoft ODBC 驱动，减少一个外网依赖：

   docker build \
     --build-arg APT_MIRROR=mirrors.huaweicloud.com \
     --build-arg INSTALL_MSSQL_ODBC=0 \
     -t database-ai-tool .

数据持久化与备份：容器内数据目录为 /data（保存 app.db 与 secret.key），已挂载到命名卷。备份：

docker run --rm -v database-ai-tool-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/database-ai-tool-backup.tgz -C /data .

连接宿主机上的 SQLite 文件：容器内的相对路径指向容器内部。需要把宿主机目录挂载进去，以只读方式挂载：

docker run ... -v /宿主机/数据库目录:/db:ro ... database-ai-tool
# 管理界面里的 SQLite 路径填写 /db/example.db

方式二：本地 Python

需要 Python 3.11+。

python -m venv .venv

# Windows
.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
copy .env.example .env        # Windows；Linux/macOS 用 cp
python -m app

打开 http://127.0.0.1:8000。

默认监听 127.0.0.1:8000。建议在 .env 中设置 ADMIN_PASSWORD，否则管理界面在本机不需要登录。

Related MCP server: mcp-knowledgebase

使用步骤

1. 启动服务：按上面的 Docker 或本地方式启动，确认 curl http://127.0.0.1:8000/healthz 返回 {"status":"ok"}。

2. 登录管理界面：浏览器打开 http://127.0.0.1:8000。设置了 ADMIN_PASSWORD 时输入用户名（默认 admin）和密码。

3. 添加数据库连接：进入「数据库连接」→「新增连接」，选择数据库类型，填写主机、端口、库名、账号密码；SQLite 只需填写文件的绝对路径。高级选项（JSON）按需填写，见下文。

4. 测试连接：保存后在列表中点「测试」，确认显示连接成功。连接创建后仍可编辑；密码留空表示不修改。

5. 创建 API Key：进入「API Keys」→「新建 Key」，勾选该 Key 允许访问的数据库，可设置过期时间。创建后立即复制完整 Key（dbt_...，只显示这一次）。

6. 接入第三方 Agent：把 MCP 端点 http://127.0.0.1:8000/mcp 和 Key 填入 Agent 配置，参考下一节。

7. 日常维护：可随时禁用/启用 Key、重置 Key（旧 Key 立即失效）、修改数据库授权；不用的连接和 Key 可直接删除。Key 列表会显示最近使用时间。

MCP 接入

• 端点：http://127.0.0.1:8000/mcp（远程部署时换成实际地址）

• 鉴权：Authorization: Bearer dbt_...，或 X-API-Key: dbt_...

• 传输：Streamable HTTP

支持 Streamable HTTP 的客户端配置示例：

{
  "mcpServers": {
    "database-ai-tool": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:8000/mcp",
      "headers": {
        "Authorization": "Bearer dbt_你的Key"
      }
    }
  }
}

只支持 stdio 的桌面客户端可以用桥接：

npx -y mcp-remote http://127.0.0.1:8000/mcp --header "Authorization: Bearer dbt_你的Key"

也可以在本机以 stdio 模式运行（需要先启动过一次管理界面，确保 Key 已创建）：

MCP_API_KEY=dbt_你的Key python -m app.mcp.stdio

MCP 工具

典型调用顺序：list_databases → list_tables → describe_table → query / sample_rows。

支持的数据库

SQL Server 需要安装对应的 ODBC 驱动（默认 ODBC Driver 18 for SQL Server），或在高级选项中指定 driver。

只读安全模型

1. 能力层：MCP 只注册读取类工具，没有任何写入工具。

2. SQL 校验（app/services/query_guard.py）：

   • 使用 sqlglot 解析，只允许单条 SELECT / WITH ... SELECT / UNION / INTERSECT / EXCEPT

   • 拒绝 INSERT / UPDATE / DELETE / DDL / SELECT INTO / 锁查询 / 多语句 / PRAGMA / ATTACH 等

   • 拒绝可执行注释 /*! ... */（MySQL）与一批危险函数（如 pg_read_file、set_config、DBMS_*、UTL_*）

   • MySQL / SQL Server 额外限制不能跨库引用

3. 数据库层：

   • SQLite 文件只读打开；PostgreSQL / MySQL 会话只读；Oracle 查询事务只读

   • 结果按连接配置的最大行数截断；查询/连接设置超时

4. Key 控制：Key 只保存 HMAC-SHA256 哈希，可随时禁用、设过期时间、重置或删除；每次 MCP 请求校验 Key，每次工具调用再次校验 Key 状态与数据库授权。

5. 管理界面：密码 Fernet 加密；可选 HTTP Basic 管理员认证；POST 请求做同源校验（防 CSRF）；默认只监听本机。

重要建议

• 为每个数据库使用只读数据库账号。应用层防护不能替代数据库权限，尤其是 SQL Server / Oracle 以及同一连接内跨 schema 访问的场景。

• 生产环境不要直接暴露本服务：默认只监听 127.0.0.1；如需远程访问，请放在 HTTPS 反向代理后，并设置 ADMIN_PASSWORD，同时把域名/地址加入 MCP_ALLOWED_HOSTS。

• data/secret.key 用于解密数据库密码，data/app.db 保存连接与 Key 哈希。请备份这两个文件；丢失 secret.key 后将无法恢复已保存的数据库密码。

高级连接选项（JSON）

表单中的「高级选项」会按数据库类型传给驱动：

// PostgreSQL：SSL / 额外连接参数
{"query": {"sslmode": "require"}}

// MySQL：字符集 / 自定义驱动参数
{"charset": "utf8mb4", "connect_args": {"ssl": {"ca": "/path/ca.pem"}}}

// SQL Server：指定 ODBC 驱动并信任自签证书
{"driver": "ODBC Driver 18 for SQL Server", "trust_server_certificate": true}

// MongoDB：认证源 / TLS
{"authSource": "admin", "tls": true}

// MongoDB：直接使用连接串（Atlas 等）
{"uri": "mongodb+srv://user:pass@cluster.example.net/?retryWrites=true"}

其中 query 会作为 SQLAlchemy URL 查询参数，connect_args 会作为 DBAPI 连接参数。

配置项（.env）

目录结构

app/
  adapters/          # SQL / MongoDB 适配器与只读连接
  services/          # 连接与 Key 业务、SQL 只读校验
  mcp/               # MCP 工具、HTTP/stdio 传输、Key 鉴权
  web/               # FastAPI 管理界面、模板与静态资源
  config.py          # 配置
  models.py          # 内部 SQLite 模型
  security.py        # 密码加密、Key 哈希
tests/               # pytest 测试
data/                # 运行时生成（已 gitignore）
Dockerfile           # 容器镜像（含 SQL Server ODBC Driver 18）
.dockerignore
docker-compose.yml   # 可选，自行按 README 示例创建

测试

pytest

测试覆盖 SQL 只读校验、加密与 Key 哈希、SQLite 只读连接与查询、MongoDB 写阶段拦截、Key 权限、管理界面流程、MCP 鉴权与完整协议调用。

已知边界

• 只允许单条 SELECT；SHOW / EXPLAIN / DESCRIBE 不作为 query 放行，请使用元数据工具。

• 同一数据库连接内的跨 schema 访问由数据库账号权限决定（MySQL/SQL Server 已做跨库名限制）。需要严格隔离时请使用独立只读账号。

• SQL Server 没有稳定的会话级只读开关，务必配合只读账号使用。

• MongoDB 的 $function/$where 等服务器端 JS 不用于写库，但可能消耗资源；请通过只读账号和超时控制风险。

• 本服务不内置 TLS；远程部署请使用反向代理。

扩展新的数据库类型

在 app/adapters/ 中实现与 SQLAdapter / MongoAdapter 相同的方法（test_connection、get_database_info、list_schemas、list_tables、describe_table、sample_rows、query），在 DB_TYPE_INFO 与 get_adapter 中注册，即可接入界面、MCP 与 Key 授权体系。