AI导哈

SQL查询生成服务

一个连接大型语言模型和PostgreSQL数据库的MCP服务器，支持自然语言生成SQL查询并执行。

  • by Akirachang
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Akirachang/text-to-SQL-MCP

使用说明

文本到SQL MCP

将任何LLM客户端连接到PostgreSQL数据库的MCP（模型上下文协议）服务器。主机LLM使用公开的模式生成SQL查询并执行它们。

See how the user interacts with the database by simply asking questions to the LLM

📋 目录

📖 概述

此MCP服务器在大型语言模型（Claude、GPT等）和PostgreSQL数据库之间提供了一个安全的桥梁，使自然语言到SQL的查询生成和执行成为可能。

💡 灵感

诞生于无数小时键入SELECT*from用户WHERE。..，我意识到我花在制作SQL查询上的时间比实际分析数据要多。为什么不直接向法学硕士询问你的数据库呢？

编写SQL是一项强大的技能，但它通常是 快速数据探索的瓶颈我构建这个是为了消除“心理上下文切换”的摩擦，即那些为了得到一个简单的答案而忘记表模式或纠结于时间戳语法的时刻。

通过利用LLM来处理样板SQL，您可以专注于要问的问题，而不是问这些问题所需的语法。

MCP工具

工具 说明
get_schema 返回所有表、列、类型和外键
get_sample_data 从指定表返回示例行
execute_query 执行SQL并返回结果（只读）

✨ 特性

  • 架构检查：检索完整的数据库架构，包括表、列、类型和外键
  • 样本数据：从任何表中获取示例行以了解数据结构
  • 查询执行：使用内置安全验证执行SQL查询
  • 只读模式：可配置的只读模式，防止数据修改
  • 查询验证：自动验证以防止危险操作
  • 行限制：可配置的最大行数，以防止压倒性的响应

安全特性

  • 查询验证：阻止危险的SQL操作（只读模式下的DROP、DELETE等）
  • 功能阻塞：防止执行危险的PostgreSQL函数
  • 多语句预防：只允许单个SQL语句
  • 只读模式：可配置为仅限于SELECT查询
  • 行限制：防止因数据过多而产生压倒性的反应

🚀 安装

先决条件

  • 紫外线 -快速Python包管理器
  • Docker和Docker Compose（用于PostgreSQL数据库）

快速开始

# Reset database and start fresh with sample data
make fresh

# View available commands
make help

# Test the connection
make check-connection

# View the database schema
make check-schema

安装uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# or with Homebrew
brew install uv

安装项目

# Install dependencies
make install
# or
uv sync

# Start local database with sample data
make fresh

💻 用法

本地开发

# Start local database
make up-db

# Run MCP server
uv run text_to_sql_mcp.server

Claude桌面集成

  1. 启动数据库：

    make up-db

  2. 添加到Claude桌面配置 (~/Library/Application Support/Claude/claude_desktop_config.json):

    {
  "mcpServers": {
    "text-to-sql": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/the/project/text-to-SQL-mcp",
        "run",
        "text-to-sql-mcp"
      ],
      "env": {
        "DATABASE_URL": "url/to/your/postgres/database"
      }
    }
  }
}

  3. 重新启动克劳德桌面 开始查询你的数据库！

Docker命令（仅限数据库）

# Start database
make up-db

# Stop database
make down

# Reset database and start fresh
make fresh

# View database logs
make logs-db

测试数据库

当你奔跑时 make fresh，PostgreSQL数据库会自动创建并填充示例电子商务数据。

示例数据库架构

表 说明 行数
users 客户账户 10
categories 产品类别 6
products 包含价格和库存的产品目录 16
orders 状态为 10的客户订单
order_items 每个订单中的单个项目 20
reviews 产品评论及评分（1-5） 14

有用的观点：

  • order_summary -包含客户信息和商品数量的订单
  • product_ratings -平均评分和评论数的产品

重置测试数据库

make fresh

# Or manually with confirmation
make reset
make up-db

测试命令

# Test database connection
make check-connection

# View database schema
make check-schema

# Run test query
make query QUERY="SELECT * FROM users LIMIT 5"

⚙️ 配置

此项目使用 Pydantic设置 用于配置管理。

创建 .env 环境变量的文件：

# Required
DATABASE_URL=postgresql://testuser:testpass@localhost:5433/testdb

# Optional
QUERY_TIMEOUT=30      # Query timeout in seconds
MAX_ROWS=1000         # Maximum rows to return
READ_ONLY=true        # Restrict to SELECT queries only

注： 使用 localhost:5433 从本地MCP服务器连接到Docker PostgreSQL数据库。

🛠️ 发展

设置

# Install development dependencies
make install-dev
# or
uv sync --all-extras

代码质量

# Format code
make format
# or
uv run black src/

# Lint code
make lint
# or
uv run ruff check src/å

清理

# Clean up containers, volumes, and Python cache
make clean

📁 项目结构

text-to-sql-mcp/
│
├── src/
│   └── text_to_sql_mcp/
│       ├── __init__.py
│       ├── server.py          # MCP server entry point
│       │
│       ├── tools/
│       │   ├── __init__.py
│       │   ├── schema.py      # get_schema, get_sample_data
│       │   └── query.py       # execute_query
│       │
│       ├── core/
│       │   ├── __init__.py
│       │   ├── database.py    # Postgres connection
│       │   └── security.py    # Query validation
│       │
│       ├── config.py            # Pydantic Settings
│       └── __init__.py
│
├── scripts/
│   ├── check_connection.py    # Test database connection
│   ├── check_schema.py        # Print schema to console
│   └── check_query.py         # Run a test query
│
├── docker-compose.yml          # PostgreSQL database setup
├── init.sql                    # Sample database initialization
├── Makefile                    # Common commands
├── pyproject.toml
├── README.md
├── .env.example
└── LICENSE

🏗️ 技术栈

核心

  • 语言：Python 3.11+
  • 包管理器: uv （星光）
  • MCP协议: mcp （官方SDK）
  • 数据库驱动: asyncpg
  • 验证: pydantic V-2型
  • 配置: pydantic-settings

基础设施

  • 数据库：PostgreSQL 15（Alpine）
  • 容器编排：Docker编写

开发工具

  • 格式化器: black
  • 代码检查工具: ruff
  • 类型检查: mypy

🔧 故障排除

连接问题

  1. 检查DATABASE_URL格式：

    postgresql://testuser:testpass@localhost:5433/testdb

  2. 确保数据库正在运行：

    make up-db
make logs-db  # Check for errors

  3. 测试连接：

    make check-connection

  4. 验证端口映射：

    docker ps  # Should show 0.0.0.0:5433->5432/tcp

  5. 从Claude Desktop查看MCP日志

    tail -n 20 -F ~/Library/Logs/Claude/mcp\*.log

查询验证错误

如果查询被阻止：

  1. 检查是否 READ_ONLY=true 已设置（只允许SELECT查询）
  2. 验证查询不使用危险函数
  3. 确保只执行一条SQL语句

性能问题

  1. 调整 QUERY_TIMEOUT 用于长时间运行的查询
  2. 减少 MAX_ROWS 如果响应太大
  3. 为数据库表添加适当的索引

额外资源

有关更多调试帮助，请参阅 MCP官方调试文档.

🤝 贡献

欢迎投稿！请随时提交拉取请求。

相关 MCP