Universal SQL MCP Server

通用SQL MCP服务器

一种模型上下文协议（MCP）服务器，提供对多个SQL数据库引擎的安全访问。该服务器使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）

查看通用SQL MCP Server运行情况的最快方法：

# Clone the repository
git clone 
cd gen-http-sql-mcp

# Install dependencies
pip install fastmcp mysql-connector-python psycopg2-binary pyodbc sqlalchemy python-dotenv

# Run the demo (creates a SQLite database with sample data)
python demo.py

# Start the MCP server
python main.py

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

安装

1. 克隆此存储库：

git clone 
cd gen-http-sql-mcp

1. 安装依赖项：

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

# Or using uv
uv sync

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

# For MySQL only
pip install fastmcp mysql-connector-python python-dotenv

# For PostgreSQL only  
pip install fastmcp psycopg2-binary python-dotenv

# For SQLite only (no additional drivers needed)
pip install fastmcp python-dotenv

# For SQL Server only
pip install fastmcp pyodbc python-dotenv

配置

1. 复制示例环境文件：

cp .env.example .env

1. 编辑 .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
# Note: SQLite doesn't require host, port, user, or password

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

常见可选设置

# Optional: Connection pool settings (not applicable for SQLite)
DB_POOL_SIZE=5
DB_MAX_OVERFLOW=10

# Optional: Connection timeout settings (in seconds)
DB_CONNECT_TIMEOUT=10
DB_READ_TIMEOUT=30
DB_WRITE_TIMEOUT=30

# Optional: Enable write operations (INSERT/UPDATE) - set to true to enable
ENABLE_WRITE_OPERATIONS=false

配置选项

• DB_TYPE：指定要使用的数据库引擎

- mysql：MySQL数据库（需要MySQL连接器python） - postgresql：PostgreSQL数据库（需要psycopg2二进制文件） - sqlite：SQLite数据库（内置Python支持） - sqlserver：SQL Server数据库（需要pyodbc）

• 启用写入操作：控制是否 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

服务器将：

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

与MCP客户端一起使用

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

工具调用示例

1. 获取数据库架构:

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

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

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

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

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

1. 测试连接:

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

安全特性

• 受控写访问：写操作只允许INSERT和UPDATE操作
• 读取访问：SELECT查询可通过专用工具获得
• 查询验证：危险的SQL关键字（DELETE、DROP、TRUNCATE等）被阻止
• 操作分离：读写操作由单独的工具处理
• 环境变量：敏感配置存储在环境变量中
• 连接管理：正确处理连接超时和清理
• 交易安全：写入操作包括自动提交和错误处理

项目结构

gen-http-sql-mcp/
├── main.py              # Main server entry point
├── database.py          # Universal database connection and management
├── tools.py             # MCP tools implementation
├── .env.example         # Environment configuration template
├── pyproject.toml       # Project dependencies and metadata
└── README.md           # This file

数据库引擎支持详细信息

MySQL

• 具有表注释、列详细信息和索引信息的完整模式自检
• 支持连接池和超时配置
• 用途 mysql-connector-python 为了获得最佳兼容性

PostgreSQL

• 全面的架构信息，包括表和列注释
• 高级索引信息和约束详细信息
• 用途 psycopg2-binary 高性能

SQLite

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

SQL Server

• 完整的表和列架构信息
• 支持Windows和SQL Server身份验证
• 通过以下方式使用ODBC连接 pyodbc
• 可配置的ODBC驱动程序选择

依赖项

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

错误处理

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

• 记录并报告数据库连接错误
• 无效的SQL查询被拒绝，并显示明确的错误消息
• 配置验证确保所需参数存在
• 中断时优雅关机

日志记录

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

基本日志记录

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

请求日志记录

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

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

# Enabled by default, shows basic request information
ENABLE_REQUEST_LOGGING=true

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

# Enable detailed logging with headers and payloads
ENABLE_DETAILED_REQUEST_LOGGING=true
REQUEST_LOG_LEVEL=DEBUG
MAX_PAYLOAD_LOG_LENGTH=5000
LOG_LEVEL=DEBUG

Docker调试环境

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

# Start debug environment with detailed logging
make debug

# View debug logs
make logs-debug

# View only MCP server debug logs
make logs-debug-mcp

调试环境支持：

• 详细的请求/响应日志记录
• HTTP标头日志记录
• 请求有效载荷日志记录
• 响应有效载荷记录
• 执行时间
• 客户信息跟踪

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

支持

对于问题和疑问：

1. 检查日志中的错误消息
2. 验证数据库配置
3. 确保您的数据库服务器可访问
4. 在存储库中创建问题