技术文档摘要

🗄️ MCP 数据库服务器

强化安全的多数据库支持 MCP 服务器 - 支持与 Cursor IDE 和 Claude 集成的 Model Context Protocol 服务器

这是一个应用了严格的安全策略的数据分析和可视化工具，支持 MySQL 和 PostgreSQL。

✨ 主要功能

🔒 安全功能（新！）

• 强制只读模式 - 只允许 SELECT 查询
• 防止 SQL 注入 - 禁止执行多语句和禁止动词
• 标识符白名单 - 验证表/列名
• 强制参数绑定 - 安全地执行查询
• 禁用 MySQL/PostgreSQL 的危险功能 - 如 INTO OUTFILE, COPY 等

🎯 多数据库支持

• MySQL/MariaDB - 完整支持（加强安全）
• PostgreSQL - 完整支持（加强安全）
• SQLite - 基本支持（开发中）

📊 可视化工具

• 生成 Mermaid ERD 图 - 将数据库模式转换为 Mermaid 图
• 生成 Markdown 表格摘要 - 清晰整理表格信息
• ASCII 性能图表 - 视觉化展示表大小和索引效率

🔍 分析功能

• 模式分析和检索
• 表统计信息
• 性能瓶颈检测
• 索引优化建议
• 查询执行计划分析

📦 安装

git clone <this-repo-url>
cd db-mcp-server
python -m venv venv
source venv/bin/activate  # 或者 venv\Scripts\activate (Windows)
pip install -r requirements.txt

⚙️ 配置

🔒 安全配置（重要！）

生产环境中必须应用以下设置：

# 强制只读模式
READ_ONLY=true
STRICT_READONLY=true

# 使用加强安全的数据库账户
DB_USER=readonly_user
DB_PASSWORD=secure_password

环境变量配置

创建 .env 文件并设置数据库信息：

cp .env.example .env

MySQL/MariaDB 配置（加强安全）

DB_TYPE=mysql
DB_HOST=localhost
DB_USER=readonly_user  # 使用只读账户
DB_PASSWORD=your_password
DB_NAME=your_database
DB_CHARSET=utf8mb4
DB_PORT=3306

PostgreSQL 配置

DB_TYPE=postgresql
DB_HOST=localhost
DB_USER=postgres
DB_PASSWORD=your_password
DB_NAME=your_database
DB_PORT= 5432
DB_SCHEMA=public

SQLite 配置

DB_TYPE=sqlite
DB_PATH=./database.sqlite

🚀 使用方法

Cursor IDE 集成

添加 MCP Server → 传输方式: stdio → 命令: python main.py

单独设置环境变量：

{
  "mcpServers": {
    "db-mcp-server": {
      "transport": "stdio",
      "command": "/path/to/venv/bin/python",
      "args": ["/path/to/db-mcp-server/main.py"],
      "env": {
        "DB_TYPE": "postgresql",
        "DB_NAME": "your_db_name",
        "DB_HOST": "localhost"
      }
    }
  }
}

🔒 安全

安全策略

此服务器应用了严格的安全部署：

• 只读模式：仅允许 SELECT 查询
• 防止 SQL 注入：禁止执行多语句和禁止动词
• 标识符验证：验证表/列名
• 参数绑定：所有用户输入均以安全方式处理

安全配置

详细的安全配置，请参阅 SECURITY.md。

数据库账户权限

重要：生产环境中必须使用只读账户：

-- MySQL 示例
CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'secure_password';
GRANT SELECT ON your_database.* TO 'mcp_readonly'@'%';

-- PostgreSQL 示例
CREATE USER mcp_readonly WITH PASSWORD 'secure_password';
GRANT CONNECT ON DATABASE your_database TO mcp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly;

🛠️ 可用工具

📋 模式工具

• get_schema - 获取整个数据库模式
• get_table_stats - 获取表统计信息
• get_sample_data - 获取样本数据
• get_column_stats - 获取列详细统计

🔍 分析工具

• execute_query - 执行安全的只读查询
• explain_query - 分析查询执行计划
• optimize_query - 提供查询优化建议
• get_db_status - 获取数据库状态信息
• get_table_size - 获取表大小信息
• get_index_usage - 获取索引使用统计
• analyze_performance - 分析性能瓶颈
• suggest_indexes - 提供索引创建建议
• optimize_tables - 提供表优化建议

🎨 可视化工具

• generate_schema_mermaid - 生成 Mermaid ERD 图
• generate_tables_summary - 生成 Markdown 表格摘要
• generate_performance_report - 生成性能分析报告（包含 ASCII 图表）

📊 使用示例

模式可视化

😊 用户: "请显示数据库模式的 ERD"
🤖 AI: 执行 generate_schema_mermaid() → 提供 Mermaid 图

性能分析

😊 用户: "请分析是否有性能问题"
🤖 AI: 执行 analyze_performance() → generate_performance_report()
     → 提供详细的性能报告，包括 ASCII 图表

表现况摘要

😊 用户: "请总结一下各表的情况"
🤖 AI: 执行 generate_tables_summary() → 提供 Markdown 表格摘要

🏗️ 项目结构

db-mcp-server/
├── main.py                 # MCP 服务器主文件
├── .env.example            # 环境变量示例文件
├── requirements.txt        # Python 依赖项
├── adapters/               # 数据库适配器
│   ├── __init__.py        
│   ├── base.py            # 基础适配器类
│   ├── mysql.py           # MySQL/MariaDB 适配器
│   └── postgresql.py      # PostgreSQL 适配器
└── tools/                 # MCP 工具模块
    ├── __init__.py
    ├── schema_tools.py     # 模式相关工具
    ├── analysis_tools.py   # 分析相关工具
    └── visualization_tools.py # 可视化相关工具

🚀 扩展性

添加新的数据库

1. 在 adapters/ 文件夹中创建新的适配器类
2. 继承 DatabaseAdapter 基类
3. 实现所需的方法
4. 在 adapters/__init__.py 的工厂函数中添加

添加新的工具

1. 在相应类别的 tools/ 模块中添加函数
2. 使用 @mcp.tool() 装饰器注册
3. 利用适配器的方法实现

📋 要求

• Python 3.8+
• 数据库:
  • MySQL/MariaDB 5.7+
  • PostgreSQL 12+
  • SQLite 3.x

🤝 贡献指南

1. Fork 该项目
2. 创建你的特性分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开一个拉取请求

📄 许可证

本项目在 MIT 许可证下发布。详情请参阅 LICENSE 文件。