AI导哈

自然语言SQL查询服务

一个允许AI助手使用自然语言查询PostgreSQL数据库的服务，支持查询日志和知识图谱学习。

  • by JeffreyBennet
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 JeffreyBennet/mcp-sql-server

使用说明

MCP SQL Server

一个模型上下文协议（MCP）服务器，允许AI助手使用自然语言查询任何PostgreSQL数据库。用简单的英语提问，获取SQL和结果。

它会随着时间的推移而学习——每个查询都会用嵌入来记录，这样类似的未来问题就会得到更好的答案。可选地连接到Neo4j知识图以存储业务术语定义和更正。

运作原理

查询管道

当你问这样的问题时 “上个月有多少用户注册？”，情况如下：

  1. 上下文收集 （并行）--在知识图中搜索领域术语，从内存中查找类似的过去查询，并列出所有可用表。
  2. 表格选择 --快速启发式根据问题中的关键字、过去的查询模式和知识图事实来选择哪些表是相关的。无需LLM电话。
  3. 架构发现 （并行）--对于每个候选表，从中发现列、类型、外键、样本行、不同值和NULL率 pg_stats。全部缓存5分钟。
  4. SQL生成 --将问题+完整模式上下文+领域知识+经过验证的查询模式发送到OpenAI，OpenAI生成PostgreSQL SELECT查询。
  5. 验证与执行 --验证SQL是只读的（没有INSERT/UPDATE/DELETE/DROP），运行EXPLAIN，然后执行。
  6. 内存日志记录 --使用嵌入向量记录问题、SQL、使用的表和结果计数，以便将来进行相似性搜索。
  7. 出现错误时重试 --如果SQL失败（列名错误、类型不匹配等），它会发现错误中提到的任何缺失表，并重试最多3次。

学习记忆

每个成功的查询都存储在 mcp_query_memory 通过OpenAI嵌入。当出现新问题时，服务器会找到最相似的过去查询，并将其SQL作为LLM的已验证模式。这意味着随着时间的推移，重复或类似的问题会得到更快、更准确的答案。

知识图谱（可选）

如果你连接Neo4j，你可以：

  • 教学术语 --告诉系统“承包商”是指 candidate 表，或者“活动”是指 status = 'Active'.
  • 正确的查询 --记录过去查询的错误，以便系统从错误中学习。
  • 种子知识 --通过预加载域定义 seed_knowledge.json.

知识图是可选的。没有它， teach_term 和 correct_query 返回错误，但是 query_database 和 search_context 仍然使用查询内存工作。

工具

工具 说明
query_database 用自然语言提问，获得SQL+结果
teach_term 教授商业术语映射（需要Neo4j）
correct_query 记录对过去查询的更正（需要Neo4j）
search_context 在知识图和查询记忆中查找业务术语的含义

设置

先决条件

  • Python 3.11+
  • PostgreSQL数据库（任何提供商——本地、AWS RDS、Azure等）
  • OpenAI API密钥（用于嵌入和SQL生成）

1.克隆和安装

git clone https://github.com/JeffreyBennet/mcp-sql-server.git
cd mcp-sql-server
chmod +x install.sh
./install.sh

或手动：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2.配置环境

复制示例并填写您的凭据：

cp .env.example .env

编辑 .env:

# Required
POSTGRES_HOST=your-host.com
POSTGRES_PORT=5432
POSTGRES_DB=your_database
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password
OPENAI_API_KEY=sk-your-openai-key

# Optional
ANTHROPIC_API_KEY=sk-ant-your-key
EMBEDDING_MODEL=text-embedding-3-small
LOG_LEVEL=INFO

3.（可选）限制表

编辑 tables.conf 仅列出您希望AI访问的表。每行一张桌子。留空或删除文件以允许所有表。

users
orders
products

4.（可选）种子知识

编辑 seed_knowledge.json 预加载域定义：

[
  ["users", "user = account = member. Table: users."],
  ["orders", "order = purchase = transaction. Table: orders. Links to users via user_id."],
  ["products", "product = item = SKU. Table: products."]
]

每个条目都是 [name, description]。这些在第一次启动时加载到Neo4j知识图中。

5.（可选）自定义说明

集 MCP_INSTRUCTIONS 在 .env 自定义AI看到的内容：

MCP_INSTRUCTIONS=You are a database assistant for our e-commerce platform. Use query_database for all data questions. Key tables: users, orders, products.

与克劳德一起使用

克劳德桌面版

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "sql-server": {
      "command": "/path/to/mcp-sql-server/venv/bin/python",
      "args": ["/path/to/mcp-sql-server/server.py"],
      "env": {
        "POSTGRES_HOST": "your-host.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "your_database",
        "POSTGRES_USER": "your_user",
        "POSTGRES_PASSWORD": "your_password",
        "OPENAI_API_KEY": "sk-your-key",
        "ANTHROPIC_API_KEY": "sk-ant-your-key"
      }
    }
  }
}

替换 /path/to/mcp-sql-server 根据实际路径（例如。， /Users/you/mcp-sql-server).

您可以将凭据放入 env 阻止（如上所示）或依赖 .env 项目目录中的文件。

克劳德代码（CLI）

添加到您的Claude Code MCP设置中：

项目级别: .claude/settings.json 在项目根目录中 用户级别: ~/.claude/settings.json

{
  "mcpServers": {
    "sql-server": {
      "command": "/path/to/mcp-sql-server/venv/bin/python",
      "args": ["/path/to/mcp-sql-server/server.py"]
    }
  }
}

或者使用Claude Code CLI：

claude mcp add sql-server /path/to/mcp-sql-server/venv/bin/python /path/to/mcp-sql-server/server.py

远程/Docker

使用Docker构建和运行：

docker build -t mcp-sql-server .
docker run -p 8000:8000 \
  -e POSTGRES_HOST=your-host \
  -e POSTGRES_PORT=5432 \
  -e POSTGRES_DB=your_db \
  -e POSTGRES_USER=your_user \
  -e POSTGRES_PASSWORD=your_pass \
  -e OPENAI_API_KEY=sk-your-key \
  mcp-sql-server

SSE服务器公开：

  • GET /health --健康检查
  • GET /sse --MCP客户端的SSE连接
  • POST /messages/ --MCP消息处理程序

配置参考

变量 必填 默认 描述
POSTGRES_HOST 是 -- PostgreSQL主机
POSTGRES_PORT 是的 5432 PostgreSQL端口
POSTGRES_DB 是 -- 数据库名称
POSTGRES_USER 是 -- 数据库用户
POSTGRES_PASSWORD 是 -- 数据库密码
OPENAI_API_KEY 是 - OpenAI API密钥（嵌入+SQL生成）
ANTHROPIC_API_KEY 否 - 人类学API密钥
EMBEDDING_MODEL 没有 text-embedding-3-small OpenAI嵌入模型
CLAUDE_MODEL 没有 claude-opus-4-6 克劳德型号名称
MCP_INSTRUCTIONS 否 （内置） 向AI显示自定义指令
DEFAULT_TABLES 无 -- 逗号分隔的回退表
NEO4J_URI 没有 bolt://localhost:7687 Neo4j连接URI
NEO4J_USER 没有 neo4j Neo4j用户名
NEO4J_PASSWORD 没有 compass2025 Neo4j密码
GRAPHITI_GROUP_ID 没有 compass 知识图组ID
RAG_MEMORY_TOP_K 没有 30 要检索的最大相似查询数
EMBEDDING_BACKFILL_LIMIT 没有 200 启动时要回填的行
LOG_LEVEL 没有 INFO 日志记录级别

文件

mcp-sql-server/
  server.py            # Main MCP server (stdio transport)
  server_sse.py        # HTTP/SSE transport for remote deployment
  requirements.txt     # Python dependencies
  .env.example         # Environment template
  tables.conf          # Table allowlist (empty = allow all)
  seed_knowledge.json  # Pre-loaded knowledge graph entries
  install.sh           # One-click setup script
  Dockerfile           # Container deployment

安全

  • 仅 SELECT 允许查询。 INSERT, UPDATE, DELETE, DROP，其他DDL/DML被阻止。
  • SQL在执行前经过验证——禁止的关键字被拒绝，以及 EXPLAIN 先跑。
  • 使用 tables.conf 以限制AI可以访问哪些表。
  • 数据库凭据存储在 .env （gitignored）或通过环境变量传递。

相关 MCP