Nlsql MCP Server Npm

NLSQL MCP服务器（Node.js）

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

快速开始

# Install globally
npm install -g nlsql-mcp-server

# Start the server
nlsql-mcp-server start

# Or run directly with npx
npx nlsql-mcp-server start

特性

• AI驱动：使用OpenAI和CrewAI将自然语言转换为SQL
• 多数据库：支持SQLite、PostgreSQL和MySQL
• 智能分析：AI驱动的数据库模式分析
• 简易安装：一个带有自动Python依赖关系管理的命令设置
• MCP协议：与Claude Desktop和其他MCP客户端兼容的完整JSON-RPC实现
• 安全执行：查询验证和可配置限制
• 样品数据：内置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. 验证安装

配置

环境设置

# Set your OpenAI API key
export OPENAI_API_KEY="your_api_key_here"

# Or create a .env file
echo "OPENAI_API_KEY=your_api_key_here" > .env

Claude桌面设置（逐步）

步骤1：安装软件包

npm install -g nlsql-mcp-server

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

1. 首选 OpenAI API密钥
2. 创建新的API密钥
3. 复制密钥（以开头 sk-)

步骤3：查找您的Claude桌面配置文件

在Windows上：

1. 按 Windows + R
2. 类型 %APPDATA%\Claude
3. 寻找 claude_desktop_config.json

在Mac上：

1. 打开查找器
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：重新启动克劳德桌面

1. 完全关闭克劳德桌面
2. 再次打开克劳德桌面
3. nlsql服务器现在应该可用

步骤6：测试它是否有效

在Claude Desktop中，尝试询问：

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

如果它有效，你会看到克劳德连接到NBA样本数据库！

用法

命令行接口

# Start the MCP server
nlsql-mcp-server start

# Start with debug mode
nlsql-mcp-server start --debug

# Test the installation
nlsql-mcp-server test

# Install/reinstall Python dependencies
nlsql-mcp-server install-deps

# Generate Claude Desktop config
nlsql-mcp-server config

# Show help
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桌面使用情况

设置完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

然后问以下问题：

• “NBA有多少支球队？”→ 返回：30支队伍
• “显示团队表中的示例数据”
• “列出来自加利福尼亚州的球队”
• “验证此SQL:从团队中选择COUNT（\*）”

测试

# Test the Node.js wrapper
npm test

# Test the underlying Python server
nlsql-mcp-server test

# Test with sample database
nlsql-mcp-server start --debug
# Then use with Claude Desktop

故障排除

常见问题

“找不到Python”

# Install Python 3.8+
# On Ubuntu/Debian:
sudo apt update && sudo apt install python3 python3-pip

# On macOS:
brew install python3

# On Windows:
# Download from python.org

“未能安装Python依赖项”

# Manual installation
nlsql-mcp-server install-deps

# Or install manually
pip3 install mcp crewai sqlalchemy pandas openai python-dotenv psycopg2-binary pymysql cryptography

“找不到OpenAI API密钥”

# Set environment variable
export OPENAI_API_KEY="your_key_here"

# Or use .env file
echo "OPENAI_API_KEY=your_key_here" > .env

“服务器无法启动”

# Debug mode for detailed logs
nlsql-mcp-server start --debug

# Test installation
nlsql-mcp-server test

调试模式

以调试模式运行以进行详细日志记录：

nlsql-mcp-server start --debug

日志文件

日志将写入：

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

集成示例

VS代码与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'
    }
});

// Handle MCP protocol communication
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许可证-请参阅 许可证 文件以获取详细信息。

鸣谢

• 原始Python服务器: NLSQL MCP服务器
• 基础应用程序: nl2sql
• 内置于: 模型上下文协议（MCP）, CrewAI, OpenAI

支持

• 问题:
• 文档:
• 讨论:

______________________________________________________________________

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