通用SQL-MCP服务器

Name: 通用SQL-MCP服务器
Author: Wunrry

作者：Wunrry5 星标更新：2025-10-06

安装使用来源：spider==github.com

项目介绍

Universal SQL MCP Server

一个提供对多种SQL数据库引擎安全访问的Model Context Protocol (MCP)服务器。此服务器使AI助手和其他MCP客户端能够通过标准化接口与各种SQL数据库进行交互。

支持的数据库

MySQL - 完整支持，包括全面的模式信息
PostgreSQL - 完整支持，包括全面的模式信息
SQLite - 完整支持，非常适合本地开发和测试
SQL Server - 完整支持，通过ODBC连接

功能

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

提供的工具

1. `get_database_schema`

检索数据库中所有表的全面信息，包括：

表名和注释
列定义，包括数据类型、约束和注释
索引信息（主键、唯一索引、普通索引）
表统计信息（估计行数、存储大小）

2. `execute_sql_query`

安全地执行SQL SELECT查询，具有以下限制：

只允许SELECT语句
阻止危险关键词（DROP、DELETE、UPDATE等）
返回结构化数据及其元数据

3. `execute_write_operation` （可选）

安全地执行SQL写操作（INSERT和UPDATE），具有以下限制：

只允许INSERT和UPDATE语句
阻止DELETE、DROP、TRUNCATE、ALTER、CREATE操作
返回受影响的行数和最后插入的ID（对于INSERT操作）
提供自动提交的事务安全性
注意：当配置中设置ENABLE_WRITE_OPERATIONS=true时，此工具才可用

4. `test_database_connection`

测试数据库连接以确保正确的配置和连接性。

快速开始

尝试演示（SQLite）

查看Universal SQL MCP Server最快的方式：

# 克隆仓库
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工具。

安装

克隆此仓库：

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

配置

复制示例环境文件：

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=
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：启用INSERT和UPDATE操作通过execute_write_operation工具
- 出于安全原因，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驱动程序。

使用方法

运行服务器

启动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')"
    }
  }
}

针对特定数据库的查询示例

PostgreSQL带RETURNING子句：

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');

SQL Server带OUTPUT子句：

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

测试连接：

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

安全特性

受控写入访问：仅允许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文件。

支持

对于问题和疑问：

检查日志中的错误消息
验证您的数据库配置
确保您的数据库服务器可访问
在仓库中创建问题