mcp-sql-tool 0.1.0

基于 MCP 协议的智能 SQL BI 工具，通过大模型自动生成 SQL 语句并执行数据库查询

MCP SQL Tool

基于 MCP (Model Context Protocol) 协议的智能 SQL BI 工具，通过大模型自动生成 SQL 语句并执行数据库查询，实现自然语言到 SQL 的转换。

快速开始

安装

pip install mcp-sql-tool

配置

# 初始化配置文件
mcp-sql-tool --init-config

# 编辑配置文件
# ~/.mcp_sql_tool/config/config.yaml

使用

# 启动服务器
mcp-sql-tool

# 测试数据库连接
mcp-sql-test-db

详细安装和使用说明请参考 INSTALLATION.md

功能特性

• 🚀 自然语言转SQL：通过 LLM 将用户自然语言查询转换为 SQL 语句
• 🗄️ 多数据库支持：支持 MySQL、PostgreSQL、SQLite、ClickHouse 等主流数据库
• 📊 Schema 感知：自动获取数据库表结构，帮助 LLM 生成准确的 SQL
• 🔒 SQL 安全控制：防止 SQL 注入，支持只读模式、查询超时等安全机制
• 📈 结果可视化：支持表格、JSON、CSV、Markdown 等多种数据展示方式
• 📝 查询历史：记录查询历史，支持查询缓存和复用

项目结构

mcp_sql_tool/
├── mcp_server/          # MCP 协议服务端
├── llm/                 # LLM 集成模块
├── database/            # 数据库连接与执行模块
├── security/            # 安全控制模块
├── storage/             # 数据存储模块
├── utils/               # 工具模块
├── config/              # 配置文件
├── main.py              # 主入口
└── requirements.txt     # 依赖包

安装

方式一：从 PyPI 安装（推荐）

pip install mcp-sql-tool

方式二：从源码安装

git clone <repository-url>
cd mcp_sql_tool
pip install -e .

详细安装说明请参考 INSTALLATION.md

3. 数据库设置

项目支持多种数据库类型，根据您的需求选择并启动相应的数据库：

MySQL

使用 Docker 启动 MySQL（推荐）：

docker run -d \
  --name mysql-server \
  -e MYSQL_ROOT_PASSWORD=your_password \
  -e MYSQL_DATABASE=your_database \
  -e MYSQL_USER=your_user \
  -e MYSQL_PASSWORD=your_password \
  -p 3306:3306 \
  mysql:8.0

或使用本地 MySQL：

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install mysql-server
sudo systemctl start mysql

# macOS (使用 Homebrew)
brew install mysql
brew services start mysql

# 创建数据库和用户
mysql -u root -p
CREATE DATABASE your_database;
CREATE USER 'your_user'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON your_database.* TO 'your_user'@'localhost';
FLUSH PRIVILEGES;

PostgreSQL

使用 Docker 启动 PostgreSQL：

docker run -d \
  --name postgres-server \
  -e POSTGRES_DB=your_database \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_PASSWORD=your_password \
  -p 5432:5432 \
  postgres:15

或使用本地 PostgreSQL：

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib
sudo systemctl start postgresql

# macOS (使用 Homebrew)
brew install postgresql
brew services start postgresql

# 创建数据库和用户
sudo -u postgres psql
CREATE DATABASE your_database;
CREATE USER your_user WITH PASSWORD 'your_password';
GRANT ALL PRIVILEGES ON DATABASE your_database TO your_user;

SQLite

SQLite 不需要单独启动，直接使用数据库文件即可：

# SQLite 数据库文件会自动创建
# 只需在配置中指定文件路径

在 config/config.yaml 中配置：

databases:
  - name: "default"
    type: "sqlite"
    database: "data/mcp_sql_tool.db"  # 数据库文件路径

ClickHouse

使用 Docker 启动 ClickHouse：

docker run -d \
  --name clickhouse-server \
  -p 8123:8123 \
  -p 9000:9000 \
  clickhouse/clickhouse-server

或使用本地 ClickHouse：

# Ubuntu/Debian
sudo apt-get install clickhouse-server clickhouse-client
sudo systemctl start clickhouse-server

# macOS (使用 Homebrew)
brew install clickhouse
brew services start clickhouse

4. 配置环境变量

创建 .env 文件或设置环境变量：

# LLM 配置
export LLM_API_KEY="your-api-key"
export LLM_PROVIDER="openai"  # openai, claude, qwen
export LLM_MODEL="gpt-4"

# 数据库配置（根据您选择的数据库类型）
export DB_HOST="localhost"
export DB_PORT="3306"  # MySQL: 3306, PostgreSQL: 5432, ClickHouse: 9000
export DB_NAME="your_database"
export DB_USER="your_user"
export DB_PASSWORD="your_password"

5. 配置文件

编辑 config/config.yaml 文件，配置数据库连接和 LLM 设置。

示例配置（MySQL）：

databases:
  - name: "default"
    type: "mysql"
    host: "${DB_HOST}"
    port: 3306
    database: "${DB_NAME}"
    user: "${DB_USER}"
    password: "${DB_PASSWORD}"
    read_only: true
    max_connections: 10

示例配置（SQLite）：

databases:
  - name: "default"
    type: "sqlite"
    database: "data/example.db"  # 文件路径
    read_only: true

6. 测试数据库连接

在启动 MCP Server 之前，建议先测试数据库连接是否正常：

MySQL：

mysql -h localhost -u your_user -p your_database

PostgreSQL：

psql -h localhost -U your_user -d your_database

SQLite：

sqlite3 data/example.db

ClickHouse：

clickhouse-client --host localhost --port 9000

如果能够成功连接，说明数据库配置正确。

或使用项目提供的测试脚本：

python scripts/test_db_connection.py

这个脚本会自动读取配置文件并测试所有配置的数据库连接。

使用方法

运行 MCP Server

项目支持三种通信协议：stdio、http 和 sse。

1. STDIO 模式（默认）

通过标准输入输出进行通信，适用于本地工具和命令行应用：

python main.py

或在 config/config.yaml 中设置：

mcp:
  transport: "stdio"

2. HTTP 模式

将 MCP Server 转换为可通过 URL 访问的 Web 服务：

在 config/config.yaml 中设置：

mcp:
  transport: "http"
  host: "0.0.0.0"
  port: 8000

运行后，服务器将在 http://0.0.0.0:8000/mcp/ 提供 MCP 服务。

3. SSE 模式

使用 Server-Sent Events 进行通信（主要用于向后兼容）：

在 config/config.yaml 中设置：

mcp:
  transport: "sse"
  host: "0.0.0.0"
  port: 8000

运行后，服务器将在 http://0.0.0.0:8000/sse/ 提供 MCP 服务。

4. 多协议模式

同时启用所有三种协议（使用多线程）：

在 config/config.yaml 中设置：

mcp:
  transport: "all"
  host: "0.0.0.0"
  http_port: 8000
  sse_port: 8001

这将同时启动：

• HTTP 服务器（http://0.0.0.0:8000/mcp/）
• SSE 服务器（http://0.0.0.0:8001/sse/）

注意：STDIO 模式不能与其他协议同时运行，因为它需要阻塞主线程来读取标准输入。如果需要 STDIO 模式，请单独使用 transport: "stdio"。

通过 MCP 协议调用

MCP Server 提供以下工具：

1. execute_sql: 执行 SQL 查询或根据自然语言生成并执行 SQL
2. get_schema: 获取数据库表结构信息
3. list_tables: 列出数据库中的所有表
4. explain_query: 解释 SQL 查询的执行计划

STDIO 模式调用示例

通过标准输入发送 JSON-RPC 请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_sql",
    "arguments": {
      "query": "查询最近7天的订单总数",
      "database": "default",
      "limit": 100
    }
  }
}

HTTP 模式调用示例

使用 HTTP POST 请求调用：

curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "execute_sql",
      "arguments": {
        "query": "查询最近7天的订单总数",
        "database": "default"
      }
    }
  }'

获取表结构示例

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_schema",
    "arguments": {
      "database": "default",
      "table": "orders"
    }
  }
}

配置说明

LLM 配置

支持以下 LLM 提供商：

• OpenAI: provider: "openai", 需要设置 OPENAI_API_KEY
• Anthropic Claude: provider: "claude", 需要设置 ANTHROPIC_API_KEY
• 通义千问: provider: "qwen", 需要设置 DASHSCOPE_API_KEY

数据库配置

支持以下数据库类型：

• MySQL: type: "mysql"
• PostgreSQL: type: "postgresql"
• SQLite: type: "sqlite"
• ClickHouse: type: "clickhouse"

安全配置

• read_only_mode: 是否只读模式（默认 true）
• max_query_timeout: 最大查询超时时间（秒）
• max_result_rows: 最大结果行数
• allowed_operations: 允许的 SQL 操作列表

架构设计

项目采用分层架构设计：

1. MCP Server 层: 处理 MCP 协议通信
2. LLM 集成层: SQL 生成核心
3. 安全控制层: SQL 验证、权限管理、查询限制
4. 数据库层: 统一接口，支持多数据库
5. 存储层: 元数据管理，独立于业务数据库

详细架构说明请参考 ARCHITECTURE.md 和 FRAMEWORK.md。

开发

运行测试

pytest tests/

代码格式化

black .
flake8 .

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！