NLSQL MCP Server (Node.js)

一个生产就绪的 Node.js 包，提供了一个 MCP（模型上下文协议）服务器，使用 AI 驱动的多代理系统将自然语言问题转换为 SQL 查询。

快速开始

# 全局安装
npm install -g nlsql-mcp-server

# 启动服务器
nlsql-mcp-server start

# 或直接运行
npx nlsql-mcp-server start

功能

• AI 驱动: 使用 OpenAI 和 CrewAI 将自然语言转换为 SQL
• 多数据库支持: 支持 SQLite、PostgreSQL 和 MySQL
• 智能分析: AI 驱动的数据库模式分析
• 简易安装: 一键设置，自动管理 Python 依赖项
• MCP 协议: 完整的 JSON-RPC 实现，兼容 Claude Desktop 和其他 MCP 客户端
• 安全执行: 查询验证和可配置限制
• 示例数据: 内置 NBA 数据库用于测试
• 生产就绪: 综合错误处理和日志记录

前提条件

• Node.js 14+: JavaScript 运行时
• Python 3.8+: 用于底层 MCP 服务器
• OpenAI API 密钥: 用于自然语言处理

安装

全局安装（推荐）

npm install -g nlsql-mcp-server

局部安装

npm install nlsql-mcp-server

该包会自动：

1. 检测你的 Python 安装
2. 安装所需的 Python 依赖项
3. 设置 NLSQL MCP 服务器
4. 验证安装

配置

环境设置

# 设置你的 OpenAI API 密钥
export OPENAI_API_KEY="your_api_key_here"

# 或创建一个 .env 文件
echo "OPENAI_API_KEY=your_api_key_here" > .env

Claude Desktop 设置（逐步指南）

第一步：安装包

npm install -g nlsql-mcp-server

第二步：获取你的 OpenAI API 密钥

1. 访问 OpenAI API 密钥页面
2. 创建一个新的 API 密钥
3. 复制密钥（以 sk- 开头）

第三步：找到你的 Claude Desktop 配置文件

在 Windows 上:

1. 按 Windows + R
2. 输入 %APPDATA%\Claude
3. 查找 claude_desktop_config.json

在 Mac 上:

1. 打开 Finder
2. 按 Cmd + Shift + G
3. 输入 ~/Library/Application Support/Claude
4. 查找 claude_desktop_config.json

在 Linux 上:

1. 打开文件管理器
2. 转到 ~/.config/Claude
3. 查找 claude_desktop_config.json

第四步：编辑配置文件

如果文件存在: 打开它，并将 nlsql 配置添加到现有的 mcpServers 部分。

如果文件不存在: 创建一个名为 claude_desktop_config.json 的新文件，内容如下：

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

重要: 将 sk-your-actual-api-key-here 替换为你真实的 OpenAI API 密钥！

第五步：重启 Claude Desktop

1. 完全关闭 Claude Desktop
2. 再次打开 Claude Desktop
3. nlsql 服务器现在应该可用

第六步：测试是否工作

在 Claude Desktop 中尝试询问：

"连接到示例数据库并显示可用的表"

如果成功，你会看到 Claude 连接到 NBA 示例数据库！

使用方法

命令行接口

# 启动 MCP 服务器
nlsql-mcp-server start

# 启动调试模式
nlsql-mcp-server start --debug

# 测试安装
nlsql-mcp-server test

# 安装/重新安装 Python 依赖项
nlsql-mcp-server install-deps

# 生成 Claude Desktop 配置
nlsql-mcp-server config

# 显示帮助
nlsql-mcp-server --help

编程使用

const NLSQLMCPServer = require('nlsql-mcp-server');

const server = new NLSQLMCPServer({
    debug: true,
    pythonExecutable: 'python3',
    env: {
        OPENAI_API_KEY: 'your_key_here'
    }
});

await server.start();

可用工具

运行时，服务器提供以下 MCP 工具：

工具	描述
connect_database	连接到 SQLite、PostgreSQL 或 MySQL
connect_sample_database	连接到内置的 NBA 示例数据库
natural_language_to_sql	使用 AI 将问题转换为 SQL
execute_sql_query	安全地执行 SQL 查询
analyze_schema	AI 驱动的数据库模式分析
get_database_info	获取表和列信息
validate_sql_query	验证 SQL 语法
get_table_sample	从表中获取样本数据
get_connection_status	检查数据库连接状态
disconnect_database	断开数据库连接

示例

Claude Desktop 使用

设置 Claude Desktop 集成后，你可以使用自然语言与数据库交互：

连接到我的示例数据库并显示模式

将这个转换为 SQL: "NBA 有多少支球队？"

显示球队表的样本数据

分析我的数据库结构并建议有用的查询

示例数据库

使用内置的 NBA 数据库进行测试（30 支球队，15 张表，包括球员、比赛、统计数据）：

使用 connect_sample_database 工具

然后询问：

• "NBA 有多少支球队？" → 返回：30 支球队
• "显示球队表的样本数据"
• "列出加利福尼亚州的球队"
• "验证此 SQL: SELECT COUNT(*) FROM team"

测试

# 测试 Node.js 包装器
npm test

# 测试底层 Python 服务器
nlsql-mcp-server test

# 使用示例数据库测试
nlsql-mcp-server start --debug
# 然后使用 Claude Desktop

故障排除

常见问题

"未找到 Python"

# 安装 Python 3.8+
# 在 Ubuntu/Debian 上：
sudo apt update && sudo apt install python3 python3-pip

# 在 macOS 上：
brew install python3

# 在 Windows 上：
# 从 python.org 下载

"无法安装 Python 依赖项"

# 手动安装
nlsql-mcp-server install-deps

# 或手动安装
pip3 install mcp crewai sqlalchemy pandas openai python-dotenv psycopg2-binary pymysql cryptography

"未找到 OpenAI API 密钥"

# 设置环境变量
export OPENAI_API_KEY="your_key_here"

# 或使用 .env 文件
echo "OPENAI_API_KEY=your_key_here" > .env

"服务器无法启动"

# 调试模式以获得详细日志
nlsql-mcp-server start --debug

# 测试安装
nlsql-mcp-server test

调试模式

使用调试模式以获得详细日志：

nlsql-mcp-server start --debug

日志文件

日志写入：

• Linux/macOS: ~/.config/nlsql-mcp-server/logs/
• Windows: %APPDATA%\nlsql-mcp-server\logs\

集成示例

VS Code 与 Continue.dev

添加到你的 Continue.dev 配置：

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

自定义应用程序

const { spawn } = require('child_process');

const mcpServer = spawn('npx', ['nlsql-m_服务器', 'start'], {
    stdio: ['pipe', 'pipe', 'pipe'],
    env: {
        ...process.env,
        OPENAI_API_KEY: 'your_key_here'
    }
});

// 处理 MCP 协议通信
mcpServer.stdout.on('data', handleMCPMessage);
mcpServer.stdin.write(JSON.stringify(mcpRequest));

性能

• 启动时间: ~2-3 秒
• 数据库操作: <1 秒（连接、查询、验证）
• AI 处理: 5-15 秒（自然语言到 SQL，模式分析）
• 内存使用: ~100-200MB
• 数据库支持: SQLite、PostgreSQL、MySQL

贡献

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 运行测试: npm test
5. 提交拉取请求

许可证

MIT 许可证 - 详情见 LICENSE 文件。

致谢

• 原始 Python 服务器: NLSQL MCP 服务器
• 底层应用: nl2sql
• 构建于: 模型上下文协议 (MCP)、CrewAI、OpenAI

支持

• 问题: GitHub 问题
• 文档: GitHub 仓库
• 讨论: GitHub 讨论

---

由 Tushar Badhwar 制作