自然语言SQL服务器

NLSQL MCP服务器（Node.js）

一个运行MCP（模型上下文协议）服务器进行对话的Node.js包 以自然语言访问您的数据库。适用于SQLite、PostgreSQL和MySQL， 并插入任何MCP客户端（Claude Desktop等）。

快速开始

# 1. Install. Auto-builds an isolated Python environment (~3 min, one time).
npm install -g nlsql-mcp-server

# 2. Verify it's ready.
nlsql-mcp-server test

然后将其添加到您的Claude Desktop配置文件中 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上， %APPDATA%\Claude\claude_desktop_config.json 在Windows上， ~/.config/Claude/claude_desktop_config.json 在Linux上）：

{
  "mcpServers": {
    "nlsql": { "command": "nlsql-mcp-server", "args": ["start"] }
  }
}

完全重新启动Claude Desktop，然后问：

连接到样本数据库，告诉我NBA有多少支球队。

就是这样-- 不需要OpenAI密钥.Claude使用 免费的关键工具和编写SQL本身。（仅限第一次呼叫，这会触发 一次性下载约52MB的样本数据库。)

需求

• Node.js 14+
• Python 3.10、3.11、3.12或3.13 — 不是3.14基础CrewAI 引擎还不支持3.14。安装程序会自动检测兼容 口译员；如果没有找到，它将打印以下内容的确切安装说明 您的操作系统。
• OpenAI API密钥 — 可选的，仅适用于服务器端AI工具 (natural_language_to_sql, analyze_schema).使用Claude Desktop，您不会 需要一个——克劳德自己处理自然语言部分。

安装--会发生什么

npm install -g nlsql-mcp-server 运行一个 postinstall 脚本：

1. 兼容Python的探测器(python3.13 → 3.12 → 3.11 → 3.10).
2. 构建a 包内的专用virtualenv 并安装slim 运行时依赖关系集。与Python系统隔离；不受影响 pep668。
3. 印刷品 Setup complete.

如果找不到兼容的Python，安装仍然会完成，但会打印 恢复说明：

macOS:   brew install python@3.13
Ubuntu:  sudo apt install python3.13 python3.13-venv
Windows: winget install Python.Python.3.13

安装其中一个，然后运行：

nlsql-mcp-server install-deps   # (re)builds the virtualenv

与Claude Desktop一起使用

重要提示： 跑 npm install -g nlsql-mcp-server 和 nlsql-mcp-server test 之前 添加下面的配置。一次性Python环境构建需要 几分钟后，无法在MCP客户端的启动握手中完成——如果 您首先将其连接进来，服务器立即退出并告诉您（在Claude中 桌面日志）运行 nlsql-mcp-server install-deps 一旦进入终端。

最小配置位于 快速开始 --不需要钥匙。启用 这 可选的服务器端AI工具 （CrewAI/OpenAI做NL→SQL内部 服务器而不是让Claude来做），添加一个 OPENAI_API_KEY:

{
  "mcpServers": {
    "nlsql": {
      "command": "nlsql-mcp-server",
      "args": ["start"],
      "env": { "OPENAI_API_KEY": "sk-your-key-here" }
    }
  }
}

你可以问克劳德什么

Connect to the sample database and show me what tables are available.

How many teams from California are in the NBA?

Connect to my Postgres at postgresql://user:pass@host:5432/db and tell me
about the schema.

Claude使用免密钥工具读取模式，编写SQL，运行它，然后 答案——除非您添加了密钥，否则循环中没有OpenAI帐户。

可用工具

两者✅ 宣传工具 只有当 OPENAI_API_KEY 已设置.没有 key，只公开了8个免密钥工具——像Claude这样功能强大的MCP客户端 桌面处理自然语言→SQL本身使用这些原语。

命令行界面

nlsql-mcp-server start            # start the MCP server (stdio)
nlsql-mcp-server start --debug    # start with verbose logging
nlsql-mcp-server test             # check venv + deps + key
nlsql-mcp-server install-deps     # (re)build the Python virtualenv
nlsql-mcp-server config           # print a Claude Desktop config snippet
nlsql-mcp-server --help

故障排除

No CrewAI-compatible Python found (need 3.10–3.13) 你的默认Python是3.14（或者范围内没有）。安装一个兼容的 (brew install python@3.13, apt install python3.13 python3.13-venv，或 winget install Python.Python.3.13)，然后运行 nlsql-mcp-server install-deps.

Claude Desktop显示服务器立即发生故障 检查MCP客户端日志。如果它说Python环境尚未构建， 跑 nlsql-mcp-server install-deps 一旦进入终端，等待它完成， 然后完全重新启动Claude Desktop。当服务器连接时会发生这种情况 在一次性环境构建完成之前。

natural_language_to_sql 返回凭据错误 OPENAI_API_KEY 未在服务器运行的环境中设置。对于Claude 桌面，把它放在 env 配置块。8个免费工具有效 没有它。

从头开始重新安装Python环境

nlsql-mcp-server install-deps

删除并重建virtualenv包。

运作原理

MCP client (Claude Desktop)
        │  JSON-RPC over stdio
        ▼
Node wrapper (index.js)  ──spawns──►  Python MCP server (package virtualenv)
                                          │
                                          ▼
                                   nl2sql + CrewAI agents
                                   SQLite / PostgreSQL / MySQL

Node层管理隔离的Python虚拟环境和进程；蟒蛇 层运行MCP协议和SQL/AI逻辑。

测试

npm test                  # Node wrapper unit tests
nlsql-mcp-server test     # installation / environment checks

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 运行测试： npm test
5. 提交拉取请求

许可证

麻省理工学院——见 许可证.

学分

• 原始Python服务器： NLSQL MCP服务器
• 基础应用： nl2sql
• 内置： 模型上下文协议, 船员AI, 开放人工智能

支持

• 问题： GitHub问题
• 存储库： GitHub

由……制造 图沙尔·巴德瓦尔