JinDaGe - universal-sql-mcp-server MCP Details

article

README

🚀 通用 SQL MCP 服务器

通用 SQL MCP 服务器是一个模型上下文协议（MCP）服务器，它为多个 SQL 数据库引擎提供安全访问。该服务器使 AI 助手和其他 MCP 客户端能够通过标准化接口与各种 SQL 数据库进行交互。

🚀 快速开始

尝试演示（SQLite）

查看通用 SQL MCP 服务器实际运行效果的最快方法：

# 克隆仓库
git clone <repository-url>
cd gen-http-sql-mcp

# 安装依赖
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv

# 运行演示（创建一个包含示例数据的 SQLite 数据库）
python demo.py

# 启动 MCP 服务器
python main.py

该演示会创建一个包含示例用户和订单的 SQLite 数据库，然后展示所有 MCP 工具的使用。

✨ 主要特性

多数据库支持：支持 MySQL、PostgreSQL、SQLite 和 SQL Server。
数据库模式检查：获取所有表、列、索引和约束的全面信息。
安全查询执行：通过内置的安全限制执行 SELECT 查询。
受控写操作：通过适当的安全控制执行 INSERT 和 UPDATE 操作。
连接测试：验证数据库连接和配置。
基于环境的配置：通过环境变量进行安全配置。
全面日志记录：提供详细的日志，用于监控和调试。
数据库特定优化：为每个数据库引擎提供定制的查询和功能。

📦 安装指南

克隆此仓库：

git clone <repository-url>
cd gen-http-sql-mcp

安装依赖：

# 使用 pip
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv

# 或者使用 uv
uv sync

可选：仅在需要时安装特定于数据库的驱动程序：

# 仅适用于 MySQL
pip install fastmcp mysql-connector-python python-dotenv

# 仅适用于 PostgreSQL
pip install fastmcp psycopg2-binary python-dotenv

# 仅适用于 SQLite（无需额外驱动程序）
pip install fastmcp python-dotenv

# 仅适用于 SQL Server
pip install fastmcp pyodbc python-dotenv

💻 使用示例

运行服务器

启动 MCP 服务器：

uv run python main.py

服务器将执行以下操作：

从环境变量加载配置。
测试数据库连接。
启动 MCP 服务器并监听请求。

与 MCP 客户端一起使用

此服务器实现了模型上下文协议，可与任何兼容 MCP 的客户端一起使用。服务器提供了三个可供 MCP 客户端调用的工具。

工具调用示例

获取数据库模式：

{
  "method": "tools/call",
  "params": {
    "name": "get_database_schema"
  }
}

执行 SQL 查询（适用于所有数据库类型）：

{
  "method": "tools/call",
  "params": {
    "name": "execute_sql_query",
    "arguments": {
      "sql_query": "SELECT * FROM users LIMIT 10"
    }
  }
}

执行写操作（适用于所有数据库类型）：

{
  "method": "tools/call",
  "params": {
    "name": "execute_write_operation",
    "arguments": {
      "sql_query": "INSERT INTO users (name, email) VALUES ('John Doe', 'john@example.com')"
    }
  }
}

特定数据库的查询示例

带有 RETURNING 子句的 PostgreSQL：

INSERT INTO users (name, email) VALUES ('Jane Doe', 'jane@example.com') RETURNING id;

带有自增功能的 SQLite：

INSERT INTO users (name, email) VALUES ('Bob Smith', 'bob@example.com');

带有 OUTPUT 子句的 SQL Server：

INSERT INTO users (name, email) OUTPUT INSERTED.id VALUES ('Alice Johnson', 'alice@example.com');

测试连接：

{
  "method": "tools/call",
  "params": {
    "name": "test_database_connection"
  }
}

📚 详细文档

配置

复制示例环境文件：

cp .env.example .env

使用你的数据库凭据编辑 .env 文件：

MySQL 配置

DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

PostgreSQL 配置

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database

SQLite 配置

DB_TYPE=sqlite
DB_NAME=/path/to/your/database.db
# 注意：SQLite 不需要主机、端口、用户或密码

SQL Server 配置

DB_TYPE=sqlserver
DB_HOST=localhost
DB_PORT=1433
DB_USER=your_username
DB_PASSWORD=your_password
DB_NAME=your_database
DB_DRIVER=ODBC Driver 17 for SQL Server

常见可选设置

# 可选：连接池设置（不适用于 SQLite）
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10

# 可选：连接超时设置（以秒为单位）
DB_CONNECT_TIMEOUT=10
DB_READ_TIMEOUT=30
DB_WRITE_TIMEOUT=30

# 可选：启用写操作（INSERT/UPDATE） - 设置为 true 以启用
ENABLE_WRITE_OPERATIONS=false

配置选项

DB_TYPE：指定要使用的数据库引擎
- mysql：MySQL 数据库（需要 mysql-connector-python）
- postgresql：PostgreSQL 数据库（需要 psycopg2-binary）
- sqlite：SQLite 数据库（Python 内置支持）
- sqlserver：SQL Server 数据库（需要 pyodbc）
ENABLE_WRITE_OPERATIONS：控制 execute_write_operation 工具是否可用
- false（默认）：仅允许只读操作（仅 SELECT 查询）
- true：通过 execute_write_operation 工具启用 INSERT 和 UPDATE 操作
- 出于安全原因，DELETE、DROP、TRUNCATE、ALTER 和 CREATE 操作始终被阻止
请求日志记录配置：
- ENABLE_REQUEST_LOGGING：启用基本请求日志记录（默认值为 true）
- ENABLE_DETAILED_REQUEST_LOGGING：启用带有标头和有效负载的详细请求日志记录（默认值为 false）
- REQUEST_LOG_LEVEL：请求日志记录的日志级别（默认值为 INFO）
- MAX_PAYLOAD_LOG_LENGTH：记录的有效负载的最大长度（默认值为 2000）
- LOG_LEVEL：通用应用程序日志级别（默认值为 INFO）

特定数据库注意事项

SQLite：仅需要 DB_NAME（文件路径）。连接池设置将被忽略。
SQL Server：可能需要额外安装 ODBC 驱动程序并指定 DB_DRIVER。
PostgreSQL：使用 psycopg2-binary 以获得最佳性能和兼容性。
MySQL：使用官方的 mysql-connector-python 驱动程序。

🔧 技术细节

安全特性

受控写访问：写操作仅允许 INSERT 和 UPDATE 操作。
读访问：通过专用工具提供 SELECT 查询。
查询验证：阻止危险的 SQL 关键字（DELETE、DROP、TRUNCATE 等）。
操作分离：读和写操作由单独的工具处理。
环境变量：敏感配置存储在环境变量中。
连接管理：通过超时和清理进行适当的连接处理。
事务安全：写操作包括自动提交和错误处理。

项目结构

gen-http-sql-mcp/
├── main.py              # 主服务器入口点
├── database.py          # 通用数据库连接和管理
├── tools.py             # MCP 工具实现
├── .env.example         # 环境配置模板
├── pyproject.toml       # 项目依赖项和元数据
└── README.md           # 此文件

数据库引擎支持详情

MySQL

支持完整的模式内省，包括表注释、列详细信息和索引信息。
支持连接池和超时配置。
使用 mysql-connector-python 以获得最佳兼容性。

PostgreSQL

提供全面的模式信息，包括表和列注释。
提供高级索引信息和约束详细信息。
使用 psycopg2-binary 以实现高性能。

SQLite

提供完整的表和列信息。
提供索引详细信息和主键信息。
非常适合开发、测试和轻量级应用程序。
无需额外安装驱动程序。

SQL Server

提供完整的表和列模式信息。
支持 Windows 和 SQL Server 身份验证。
通过 pyodbc 使用 ODBC 连接。
可配置 ODBC 驱动程序选择。

依赖项

fastmcp：用于构建 MCP 服务器的 FastMCP 框架。
mysql-connector-python：Python 的官方 MySQL 驱动程序。
psycopg2-binary：Python 的 PostgreSQL 适配器。
pyodbc：用于 SQL Server 的 ODBC 数据库连接。
sqlalchemy：SQL 工具包和对象关系映射库。
python-dotenv：环境变量加载。
sqlite3：Python 内置的 SQLite 支持（无需额外安装）。

错误处理

服务器包含全面的错误处理：

记录并报告数据库连接错误。
以清晰的错误消息拒绝无效的 SQL 查询。
配置验证确保所需参数存在。
在中断时优雅关闭。

日志记录

服务器提供全面的日志记录功能：

基本日志记录

连接状态和数据库信息。
查询执行结果和性能。
带有上下文的错误消息。
服务器启动和关闭事件。

请求日志记录

服务器包含高级请求日志记录中间件，以帮助调试客户端连接问题：

简单请求日志记录（默认）

# 默认启用，显示基本请求信息
ENABLE_REQUEST_LOGGING=true

详细请求日志记录（调试模式）

# 启用带有标头和有效负载的详细日志记录
ENABLE_DETAILED_REQUEST_LOGGING=true
REQUEST_LOG_LEVEL=DEBUG
MAX_PAYLOAD_LOG_LENGTH=5000
LOG_LEVEL=DEBUG

Docker 调试环境

要调试客户端连接问题，请使用调试环境：

# 启动带有详细日志记录的调试环境
make debug

# 查看调试日志
make logs-debug

# 仅查看 MCP 服务器的调试日志
make logs-debug-mcp

调试环境启用以下功能：

详细的请求/响应日志记录。
HTTP 标头日志记录。
请求有效负载日志记录。
响应有效负载日志记录。
执行计时。
客户端信息跟踪。

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

支持

若遇到问题或有疑问，请按以下步骤操作：

检查日志以获取错误消息。
验证你的数据库配置。
确保你的数据库服务器可访问。
在仓库中创建一个问题。