Microsoft SQL Server MCP Server (MSSQL)

🚀 MS SQL MCP サーバー日本語ドキュメント

MS SQL MCP（Microsoft SQL Machine Learning Platform）サーバーは、Microsoft SQL データベースの探索と操作を支援するための、モジュール化された拡張可能なツールです。クエリの実行、テーブル構造の表示、データベースの探索などの機能を提供することで、SQL データベースとのやり取りを簡素化します。

🚀 クイックスタート

MS SQL MCP サーバーを使用するには、まず環境設定を行い、その後サーバーを起動してデータベースとの接続を確立します。具体的な手順は以下の通りです。

環境設定

.env ファイルを使用して、サーバーがデータベースに接続する方法や動作方式を設定します。以下に設定項目の例を示します。

# データベース接続設定
DB_USER=your_username           # SQL Server ユーザー名
DB_PASSWORD=your_password       # SQL Server パスワード
DB_SERVER=your_server_name      # サーバーホスト名または IP アドレス（例：localhost, 10.0.0.1, myserver.database.windows.net）
DB_DATABASE=your_database_name  # 接続するデータベース名

# サーバー設定
PORT=3333                       # HTTP/SSE サーバーがリッスンするポート
TRANSPORT=stdio                 # 接続方法：'stdio'（Claude Desktop 用）または 'sse'（ネットワーク接続用）
SERVER_URL=http://localhost:3333 # SSE トランスポートを使用する場合のベース URL（PORT 設定と一致する必要があります）

# 高度な設定
DEBUG=false                     # 詳細なログ記録を有効にするには 'true' に設定（デバッグ時に便利）
QUERY_RESULTS_PATH=/path/to/query_results  # クエリ結果を保存するフォルダのパス

サーバー起動

接続タイプに応じて、以下のコマンドでサーバーを起動します。

stdio トランスポート

Claude Desktop を直接使用して接続する場合に使用します。

# .env ファイルで TRANSPORT=stdio を設定
npm start

HTTP/SSE トランスポート

ネットワークを介して接続する場合に使用します。

# .env ファイルで TRANSPORT=sse を設定
npm run sse

✨ 主な機能

データベース接続管理

database.mjs を使用して、SQL Server の接続プールを管理し、クエリの実行やトランザクションの処理を行います。

ツール登録と操作

tools.mjs では、すべてのデータベースツールを MCP サーバーに登録し、SQL クエリやテーブル構造の表示、データベースの探索などの機能を提供します。

データベースリソースの公開

resources.mjs を通じて、データベースのメタデータを公開し、AI が使用できる形式でデータベース構造情報を提供します。

結果のページネーション

pagination.mjs では、大きな結果セットを処理するためのページネーション機能を実装しています。

エラー処理

errors.mjs では、さまざまな障害シナリオに対応するカスタムエラータイプを定義し、JSON-RPC エラーの形式を整えます。

ログ記録

logger.mjs を使用して、Winston を用いたログ記録を行い、未捕捉の例外や拒否をキャプチャします。

📦 インストール

本サーバーを使用するには、必要な依存関係をインストールする必要があります。以下のコマンドを実行してください。

npm install

💻 使用例

基本的な使用法

SQL Server への接続

const { Database } = require('mssql-mcp');

async function connect() {
    const db = new Database({
        config: {
            user: 'your_username',
            password: 'your_password',
            server: 'localhost',
            database: 'your_database'
        }
    });

    try {
        await db.connect();
        console.log('SQL Server に接続しました。');
    } catch (error) {
        console.error('データベースに接続できません:', error);
    }
}

connect();

クエリの実行

async function queryExample() {
    const db = new Database({
        config: {
            user: 'your_username',
            password: 'your_password',
            server: 'localhost',
            database: 'your_database'
        }
    });

    try {
        await db.connect();
        const result = await db.query('SELECT TOP 5 * FROM YourTable');
        console.log('クエリ結果:', result);
    } catch (error) {
        console.error('クエリの実行中にエラーが発生しました:', error);
    } finally {
        await db.disconnect();
    }
}

queryExample();

ページネーションクエリの実行

async function paginatedQuery() {
    const db = new Database({
        config: {
            user: 'your_username',
            password: 'your_password',
            server: 'localhost',
            database: 'your_database'
        },
        options: {
            pageNumber: 2,
            pageSize: 10
        }
    });

    try {
        await db.connect();
        const result = await db.query('SELECT * FROM YourTable ORDER BY Id');
        console.log('ページネーション結果:', result);
    } catch (error) {
        console.error('ページネーションクエリの実行中にエラーが発生しました:', error);
    } finally {
        await db.disconnect();
    }
}

paginatedQuery();

高度な使用法

ログ記録の制御

環境変数 DEBUG を設定することで、詳細なログ記録を有効または無効にすることができます。

# デバッグモードを有効にする
DEBUG=true npm start

# デバッグモードを無効にする（デフォルト）
npm start

🔧 技術詳細

核心コンポーネント

database.mjs - データベース接続

• SQL Server 接続プールを管理します。
• リトライロジックとエラー処理を備えたクエリ実行機能を提供します。
• データベースの接続、トランザクション、および設定を処理します。
• SQL ステートメントのクリーニングとエラー情報のフォーマットを行うツールを含みます。

tools.mjs - ツール登録

• すべてのデータベースツールを MCP サーバーに登録します。
• ツールの検証とパラメーターのチェックを実装します。
• SQL クエリ、テーブル構造の表示、およびデータベースの探索の核心機能を提供します。
• ツールの呼び出しをデータベース操作にマッピングします。

resources.mjs - データベースリソース

• リソースエンドポイントを介してデータベースのメタデータを公開します。
• スキーマ情報、テーブルリスト、およびプロシージャのドキュメントを提供します。
• AI が使用できる形式でデータベース構造情報をフォーマットします。
• データベースを探索するためのユーティリティツールを含みます。

pagination.mjs - 結果ナビゲーション

• カーソルベースのページネーションを実装して、大きな結果セットを処理します。
• 次のページ/前のページのカーソルを生成します。
• SQL クエリをページネーションをサポートする形式に変換します。
• SQL Server の OFFSET/FETCH ページネーション構文を処理します。

errors.mjs - エラー処理

• さまざまな障害シナリオに対応するカスタムエラータイプを定義します。
• JSON-RPC エラーのフォーマットを実装します。
• 読みやすいエラーメッセージを提供します。
• グローバルなエラー処理ミドルウェアを含みます。

logger.mjs - ログシステム

• Winston を使用したログ記録を設定し、複数のトランスポート方式をサポートします。
• コンテキストを考慮したログ記録機能を提供します。
• ログのローテーションとフォーマットを処理します。
• 未捕捉の例外と未処理の拒否をキャプチャします。

環境設定

.env ファイルを使用して、MS SQL MCP サーバーの動作を設定します。以下は各設定項目の詳細です。

データベース探索

MS SQL MCP サーバーは、強力なデータベース探索機能を提供します。

• テーブル構造の表示：テーブルの列情報をツリービューまたはテーブル形式で表示します。
• データのプレビュー：特定の行数を選択して、迅速なデータ分析を行うことができます。
• メタデータの抽出：データベース、テーブル、および列レベルの詳細なメタデータを提供します。

エラー処理

エラーが発生した場合、MS SQL MCP サーバーは詳細なエラー情報を提供します。以下は一般的なエラーシナリオと解決策です。

接続エラー

• 原因：データベースの資格情報が正しくないか、ネットワーク問題があります。
• 解決策：ユーザー名、パスワード、およびサーバーアドレスが正しいことを確認し、ネットワーク接続が正常であることを確認します。

クエリエラー

• 原因：構文エラーまたは権限不足です。
• 解決策：SQL クエリの構文が正しいことを検証し、ユーザーがクエリを実行する権限を持っていることを確認します。

リソース制限

• 原因：データベースのリソースが枯渇しています（例：メモリ不足）。
• 解決策：クエリのパフォーマンスを最適化し、同時に実行するクエリの数を減らすか、データベースサーバーのリソースを増やします。

📚 まとめ

MS SQL MCP サーバーは、Microsoft SQL データベースとの効率的なやり取りを可能にする、強力で柔軟なツールです。モジュール化された設計と豊富な機能セットにより、基本的なクエリから複雑なデータ分析まで、さまざまなタスクを簡単に実行できます。