📌Overview

Purpose: To provide a secure and efficient means for AI systems to access various databases for data analysis without directly connecting to them.

Overview: MCP Database Utilities is a versatile tool that serves as a secure bridge between AI systems and databases (like SQLite, MySQL, and PostgreSQL). It ensures safe data access and analysis, enabling AI to read data without the risk of data modification.

Key Features:

Strict Read-Only Access: Only allows SELECT queries, preventing any data modification, thereby ensuring data integrity.
Local Processing: All data handling occurs locally, with no data sent to external servers, enhancing privacy and data security.

MCP 数据库工具

English | 技术指南

什么是 MCP Database Utilities？

MCP Database Utilities 是一个多功能的 MCP 服务，使您的 AI 通过统一的连接配置安全访问各种类型的数据库（SQLite、MySQL、PostgreSQL 等）进行数据分析。

它是 AI 系统和数据库之间的安全桥梁，允许 AI 在不直接访问数据库或冒数据修改风险的情况下读取和分析数据。

安全和隐私：我们的首要任务

MCP 数据库工具采用安全优先的架构设计，适合注重数据保护的企业、初创公司和个人用户。安全措施包括：

数据保护

严格只读：仅允许 SELECT 查询，禁止数据修改
无直接数据库访问：AI 通过安全服务与数据库交互，永不直接连接
隔离连接：单独管理并严格隔离每个数据库连接
按需连接：仅在需要时连接，任务完成后立即断开
自动超时：长时间运行的操作自动终止，防止资源滥用

隐私保障

本地处理：所有数据在本地机器上处理，无数据发送至外部服务器
最小数据暴露：仅返回请求数据，限制暴露范围
凭证保护：连接凭证永不暴露给 AI 模型
敏感数据屏蔽：密码和连接信息在日志中自动隐藏

企业级安全

SSL/TLS 支持：加密连接远程数据库
配置分离：YAML 配置文件消除解释风险
用户控制访问：由用户决定哪些数据库可被访问
安全默认设置：开箱即用的安全配置，无需额外调整

详见技术指南中的通信模式与安全架构。

为什么使用 MCP Database Utilities？

通用 AI 支持：适用于任何支持 MCP 协议的 AI 系统
多数据库支持：统一接口连接 SQLite、MySQL、PostgreSQL
简单配置：所有连接通过单一 YAML 文件管理
高级功能：支持表格浏览、架构分析和查询执行

系统要求

Python 3.10 或更高版本
任选其一安装方式：
- uvx 包管理器
- Docker Desktop
- Smithery（Node.js 14+）
支持数据库：
- SQLite 3.x
- PostgreSQL 12+
- MySQL 8+
支持 AI 客户端：
- Claude Desktop
- Cursor
- 任何兼容 MCP 的客户端

开始使用

1. 安装指南

选择以下一种方法安装：

方式A：使用 uvx（推荐）

安装 uv 和 uvx：

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后验证：

uv --version

创建配置文件 config.yaml，填写数据库连接详情：

connections:
  postgres:
    type: postgres
    host: localhost
    port: 5432
    dbname: my_database
    user: my_user
    password: my_password

关于高级配置（SSL、连接池等），请参阅配置示例集锦。

配置 AI 客户端的 MCP 配置文件，添加：

"dbutils": {
  "command": "uvx",
  "args": [
    "mcp-dbutils",
    "--config",
    "/完整/路径/到您的/config.yaml"
  ]
}

注意替换配置文件路径，确保 uvx 已正确安装。

方式B：使用 Docker 手动安装

安装 Docker Desktop（若无）。
创建配置文件。
配置 AI 客户端的 MCP 配置文件，添加：

"dbutils": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "-v",
    "/完整/路径/到您的/config.yaml:/app/config.yaml",
    "-v",
    "/完整/路径/到您的/sqlite.db:/app/sqlite.db",  // SQLite 数据库时需要
    "mcp/dbutils",
    "--config",
    "/app/config.yaml"
  ]
}

注意替换路径，非 SQLite 数据库应删除 sqlite.db 卷映射。

方式C：使用 Smithery（Claude 一键配置）

自动安装并配置服务到 Claude：

npx -y @smithery/cli install @donghao1393/mcp-dbutils --client claude

安装完毕后，直接进入使用服务阶段。

2. 使用服务

安装并配置完成后，您的 AI 可执行：

列出数据库表
查看表结构
安全执行 SQL 查询
跨数据库数据分析

验证流程：

询问 AI 是否能连接到数据库。
AI 若确认连通，尝试请求列出数据库表。
如有问题，检查配置文件语法、数据库连接信息、AI MCP 配置及数据库访问权限。

交互示例

您："能否列出我的 my-postgres 数据库中的所有表？"

AI："以下是您的 my-postgres 数据库表：

customers（客户）
products（产品）
orders（订单）
inventory（库存）
employees（员工）"

您："customers 表结构是什么？"

AI："customers 表结构：

id（整数，主键）
name（文本）
email（文本）
registration_date（日期）
last_purchase（日期）
total_spent（数值）"

您："过去一个月有多少客户购买？"

AI："查询结果显示，过去一个月有 128 位客户购买，总额 25,437.82 元。"

可用工具

dbutils-list-tables：列出数据库表
dbutils-run-query：执行 SQL 查询（只读）
dbutils-get-stats：获取表统计信息
dbutils-list-constraints：列出表约束
dbutils-explain-query：查询执行计划
dbutils-get-performance：数据库性能指标
dbutils-analyze-query：查询优化分析

需要更多帮助？

技术文档 - 适用于开发和高级用户
GitHub Issues - 报告问题或请求功能
Smithery - 简化安装和更新

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。