Nlsql MCP Server Npm

🚀 NLSQL MCP Server (Node.js)

このNode.jsパッケージは、AIベースのマルチエージェントシステムを用いて、自然言語の質問をSQLクエリに変換するためのMCP（Model Context Protocol）サーバーを提供し、本番環境での使用にも耐えます。

🚀 クイックスタート

# グローバルにインストール
npm install -g nlsql-mcp-server

# サーバーを起動
nlsql-mcp-server start

# またはnpxで直接実行
npx nlsql-mcp-server start

✨ 主な機能

• AIベース：OpenAIとCrewAIを使用して自然言語をSQLに変換
• マルチデータベース対応：SQLite、PostgreSQL、MySQLをサポート
• スマート分析：AIによるデータベーススキーマ分析
• 簡単なインストール：1コマンドでのセットアップと自動Python依存関係管理
• MCPプロトコル：Claude Desktopや他のMCPクライアントと互換性のある完全なJSON - RPC実装
• 安全な実行：クエリ検証と設定可能な制限
• サンプルデータ：テスト用の組み込み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：設定ファイルを編集

ファイルが存在する場合： 開いて、既存のmcpServersセクションにnlsql設定を追加する。

ファイルが存在しない場合： 次の内容で新しい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();

基本的な使用法

// 元のコードとコメントを保持
const NLSQLMCPServer = require('nlsql-mcp-server');

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

await server.start();

高度な使用法

// 高度なシナリオでは、必要に応じて追加の設定や操作を行うことができます。
// 例えば、特定のデータベースに接続する場合や、カスタムの環境変数を設定する場合など。
const NLSQLMCPServer = require('nlsql-mcp-server');

const customEnv = {
    ...process.env,
    OPENAI_API_KEY: 'your_key_here',
    CUSTOM_VARIABLE: 'custom_value'
};

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

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で使用

統合例

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秒（接続、クエリ、検証）
• AI処理：5 - 15秒（自然言語からSQL、スキーマ分析）
• メモリ使用量：約100 - 200MB
• データベースサポート：SQLite、PostgreSQL、MySQL

🔧 技術詳細

トラブルシューティング

一般的な問題

"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\

📄 ライセンス

MITライセンス - 詳細はLICENSEファイルを参照してください。

クレジット

• 元のPythonサーバー：NLSQL MCP Server
• 基盤となるアプリケーション：nl2sql
• 使用技術：Model Context Protocol (MCP), CrewAI, OpenAI

サポート

• 問題報告：GitHub Issues
• ドキュメント：GitHub Repository
• ディスカッション：GitHub Discussions

作成者: Tushar Badhwar