Nlsql MCP Server Npm

🚀 NLSQL MCP Server (Node.js)

NLSQL MCP Server是一个基于Node.js的生产级软件包，借助人工智能多智能体系统，它能将自然语言问题转换为SQL查询，为数据库操作带来了极大的便利。

🚀 快速开始

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

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

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

✨ 主要特性

• 人工智能驱动：利用OpenAI和CrewAI将自然语言转换为SQL。
• 多数据库支持：支持SQLite、PostgreSQL和MySQL。
• 智能分析：通过人工智能进行数据库模式分析。
• 易于安装：一键式安装，自动管理Python依赖。
• MCP协议：完整实现JSON - RPC，与Claude Desktop和其他MCP客户端兼容。
• 安全执行：提供查询验证和可配置的限制。
• 示例数据：内置NBA数据库，方便测试。
• 生产就绪：具备全面的错误处理和日志记录功能。

📦 安装指南

全局安装（推荐）

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设置（分步指南）

步骤1：安装软件包

npm install -g nlsql-mcp-server

步骤2：获取你的OpenAI API密钥

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

步骤3：找到你的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。

步骤4：编辑配置文件

如果文件已存在：打开文件，并将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密钥！

步骤5：重启Claude Desktop

1. 完全关闭Claude Desktop。
2. 重新打开Claude Desktop。
3. 此时nlsql服务器应该可用。

步骤6：测试是否正常工作

在Claude Desktop中，尝试询问：

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

如果一切正常，你将看到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工具：

具体使用示例

Claude Desktop使用示例

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

Connect to my sample database and show me the schema

Convert this to SQL: "How many teams are in the NBA?"

Show me sample data from the team table

Analyze my database structure and suggest useful queries

示例数据库使用

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

Use the connect_sample_database tool

然后可以提出以下问题：

• "How many teams are in the NBA?" → 返回：30支球队
• "Show me sample data from the team table"
• "List teams from California"
• "Validate this SQL: SELECT COUNT(*) FROM team"

🧪 测试方法

# 测试Node.js包装器
npm test

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

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

⚙️ 故障排除

常见问题

"Python not found"

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

# macOS系统：
brew install python3

# Windows系统：
# 从python.org下载

"Failed to install Python dependencies"

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

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

"OpenAI API key not found"

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

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

"Server won't start"

# 以调试模式启动以查看详细日志
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-mcp-server', '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秒（连接、查询、验证）
• 人工智能处理：5 - 15秒（自然语言转SQL、模式分析）
• 内存使用：约100 - 200MB
• 数据库支持：SQLite、PostgreSQL、MySQL

🤝 贡献指南

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

📄 许可证

本项目采用MIT许可证，详情请参阅 LICENSE 文件。

👏 鸣谢

• 原始Python服务器：NLSQL MCP Server
• 底层应用程序：nl2sql
• 使用的技术：Model Context Protocol (MCP)、CrewAI、OpenAI

📞 支持与反馈

• 问题反馈：GitHub Issues
• 文档查阅：GitHub Repository
• 讨论交流：GitHub Discussions

作者：Tushar Badhwar