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