AI导哈

自然语言SQL查询工具

一个允许用户通过自然语言检查PostgreSQL数据库模式并运行只读查询的MCP服务器。

  • by Kamalesh-Kavin
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Kamalesh-Kavin/sql-mcp

使用说明

sql-mcp

一个模型上下文协议（MCP）服务器，允许Claude检查PostgreSQL 数据库模式，并使用自然语言运行只读查询。

它做什么

工具 说明
list_tables 列出所有表/视图（名称、列数、主键）
describe_table 一个表的完整架构：列、类型、PK、FK
run_query 执行只读SQL查询，以表的形式返回结果
get_full_schema 将整个模式转储为JSON（用于复杂的多表查询）

建筑

Claude Desktop
     │  MCP (stdio)
     ▼
sql_mcp/server.py     ← MCP server, 4 tools, async SQLAlchemy engine
     └── database.py  ← async engine, schema introspection, safe run_select

关键设计决策：

  • 异步端到端 --SQLAlchemy异步引擎+asyncpg驱动程序意味着每个数据库 呼叫无阻塞。不 asyncio.to_thread() 需要（与devops-mcp不同）。
  • 只读执行 — run_select() 拒绝任何不符合以下条件的声明 从...开始 SELECT / WITH / EXPLAIN / TABLE 在它到达DB之前。
  • 排帽 --结果上限为 MAX_QUERY_ROWS （默认值500）以防止 避免失控的查询淹没上下文窗口。
  • 架构筛选 — ALLOWED_SCHEMAS 限制Claude可以使用哪些模式 看，这样您就可以安全地将其指向生产数据库。

需求

  • Python 3.11+
  • 紫外线 包管理器
  • Docker（用于演示Postgres容器）

设置

git clone https://github.com/Kamalesh-Kavin/sql-mcp
cd sql-mcp

# Install dependencies
uv sync

# Copy and fill in your DB URL
cp .env.example .env

启动演示数据库（一次性）

# Create network + volume
docker network create sql_mcp_network
docker volume create sql_mcp_data

# Start Postgres on port 5434
# (5433 may be taken by a local Postgres instance on macOS)
docker run -d \
  --name sql-mcp-db \
  --network sql_mcp_network \
  -v sql_mcp_data:/var/lib/postgresql/data \
  -e POSTGRES_USER=sql_mcp_user \
  -e POSTGRES_PASSWORD=sql_mcp_pass \
  -e POSTGRES_DB=sql_mcp_demo \
  -p 5434:5432 \
  postgres:16

# Seed the e-commerce demo schema
uv run python -m sql_mcp.seed

运行烟雾测试

uv run python smoke_test.py

所有6个测试部分都应打印 PASS.

连接到克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

"sql-assistant": {
  "command": "/Users/yourname/.local/bin/uv",
  "args": [
    "--directory", "/path/to/sql-mcp",
    "run", "sql-mcp"
  ]
}

重新启动Claude Desktop，然后尝试：

  • “列出数据库中的所有表”
  • “描述订单表”
  • “按总支出显示前5位客户”
  • “每个状态下有多少个订单？”
  • “哪些产品从未被订购过？”

演示模式

users ──< orders ──< order_items >── products
表 说明
users 来自8个国家的8位客户
products 4个类别的10个产品
orders 10个订单状态（待定/已支付/已发货/已取消）
order_items 16个将订单与产品关联起来的行项目

环境变量(.env)

变量 默认值 描述
DATABASE_URL -- asyncpg连接URL(postgresql+asyncpg://...)
ALLOWED_SCHEMAS public 要公开的逗号分隔模式；空白=全部
MAX_QUERY_ROWS 500 对每个查询返回的行设置硬上限

相关 MCP