Db Assistant

基于 MCP (Model Context Protocol) 协议的数据库操作服务器，使用 FastMCP 框架构建，为 AI 客户端提供数据库连接、查询、Schema 探索、数据分析和 SQL 生成工具。

特性

• 26个MCP工具，覆盖数据库操作全流程
• SQLite内置支持，启动即用，无需额外安装数据库
• PostgreSQL可选支持，通过 psycopg2 扩展
• 自动示例数据库，包含 employees / departments / salaries 三张表和索引
• pandas数据分析，提供表统计、列统计、数据质量报告、值分布等高级分析
• SQL构建器，参数化生成 SELECT / INSERT / UPDATE / CREATE TABLE / JOIN
• 安全防护，标识符验证防止 SQL 注入，SELECT/UPDATE 分离执行

快速开始

安装依赖

pip install -r requirements.txt

启动服务器

python server.py

服务器启动后会自动创建示例数据库 sample.db 并连接。

在MCP客户端中配置

在 MCP 客户端配置文件中添加：

{
  "mcpServers": {
    "db-assistant": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/mcp-db-assistant"
    }
  }
}

示例数据库

启动时自动创建的 sample.db 包含以下表：

departments（部门表）

列名	类型	说明
id	INTEGER PK	部门ID
name	TEXT	部门名称
manager_id	INTEGER FK	部门经理(引用employees.id)
location	TEXT	所在地
budget	REAL	预算

employees（员工表）

列名	类型	说明
id	INTEGER PK	员工ID
name	TEXT	姓名
department_id	INTEGER FK	部门ID(引用departments.id)
position	TEXT	职位
hire_date	TEXT	入职日期
email	TEXT UNIQUE	邮箱
is_active	INTEGER	是否在职(1=是, 0=否)

salaries（工资表）

列名	类型	说明
id	INTEGER PK	工资记录ID
employee_id	INTEGER FK	员工ID(引用employees.id)
amount	REAL	工资金额
effective_date	TEXT	生效日期
end_date	TEXT	结束日期(NULL表示当前有效)

工具列表

连接管理（4个）

工具	说明
connect_sqlite(db_path)	连接 SQLite 数据库
connect_postgres(host, port, db, user, password)	连接 PostgreSQL（可选）
list_databases()	列出所有数据库
get_connection_status()	获取当前连接状态

查询工具（6个）

工具	说明
execute_query(sql)	执行 SELECT 查询，返回 Markdown 表格
execute_update(sql)	执行 INSERT/UPDATE/DELETE
query_with_pagination(sql, page, page_size)	分页查询
export_query_result(sql, format)	导出结果（CSV/JSON/Markdown）
explain_query(sql)	执行计划分析
count_rows(table_name)	统计表行数

Schema 探索（5个）

工具	说明
list_tables()	列出所有表
describe_table(table_name)	表结构详情
list_indexes(table_name)	列出索引
get_table_ddl(table_name)	获取建表语句
get_foreign_keys(table_name)	获取外键关系

数据分析（6个）

工具	说明
table_stats(table_name)	表统计（行数/列数/大小）
column_stats(table_name, column)	列统计（distinct/NULL/min/max/avg）
data_quality_report(table_name)	数据质量报告（完整性/唯一性）
table_sample(table_name, n)	表采样数据
null_analysis(table_name)	NULL 值分析
value_distribution(table_name, column, bins)	值分布分析（直方图）

SQL 构建（5个）

工具	说明
build_select(table, columns, where, order_by, limit)	构建 SELECT 语句
build_insert(table, data)	构建 INSERT 语句（参数化）
build_update(table, set_values, where)	构建 UPDATE 语句（参数化）
build_create_table(table_name, columns)	构建 CREATE TABLE 语句
build_join(table1, table2, on, select_columns, join_type)	构建 JOIN 查询

项目结构

mcp-db-assistant/
├── server.py                # MCP Server入口（创建示例数据库+启动服务）
├── mcp_db_assistant/
│   ├── __init__.py           # 包初始化（创建FastMCP实例+注册工具）
│   ├── connection.py         # 数据库连接管理（4个工具）
│   ├── query_tools.py       # 查询工具（6个工具）
│   ├── schema_tools.py      # Schema探索工具（5个工具）
│   ├── analysis.py          # 数据分析工具（6个工具）
│   └── sql_builder.py       # SQL构建工具（5个工具）
├── README.md
├── SKILL.md
└── requirements.txt

技术栈

• FastMCP - MCP协议Python实现
• sqlite3 - Python标准库，SQLite数据库引擎
• pandas - 数据分析和处理
• psycopg2（可选） - PostgreSQL数据库适配器

许可证

MIT License