SuzieQ 用 MCP サーバー

このプロジェクトは、言語モデルやその他の MCP クライアントが REST API を介して SuzieQ ネットワーク観測インスタンスと対話できるようにするモデル コンテキスト プロトコル (MCP) サーバーを提供します。

概要

サーバーは、SuzieQ のコマンドを MCP ツールとして公開します。

• run_suzieq_show : 詳細なネットワーク状態テーブルを照会するには、「show」コマンドにアクセスします。

• run_suzieq_summarize : 集計された統計情報と要約を取得するには、「summarize」コマンドにアクセスします。

これらのツールを使用すると、クライアント (Claude Desktop など) はさまざまなネットワーク状態テーブル (インターフェイス、BGP、ルートなど) を照会してフィルターを適用し、SuzieQ インスタンスから直接結果を取得できます。

前提条件

• **Python:**バージョン 3.8 以上を推奨します。

• **uv:**高速な Python パッケージインストーラーおよびリゾルバー。(インストールガイド)

• SuzieQ インスタンス: REST API が有効になっていてアクセス可能な実行中の SuzieQ インスタンス。

• SuzieQ API エンドポイントとキー: SuzieQ API の URL (例: http://your-suzieq-host:8000/api/v2 ) と有効な API キー ( access_token ) が必要です。

インストールとセットアップ

Smithery経由でインストール

Smithery経由で Claude Desktop 用の suzieq-mcp を自動的にインストールするには:

手動でインストールする

1. **コードを取得する:**このリポジトリを複製するか、 main.pyおよびserver.pyファイルを専用のプロジェクト ディレクトリにダウンロードします。

2. **仮想環境の作成:**ターミナルでプロジェクト ディレクトリに移動し、 uvを使用して仮想環境を作成します。

   uv venv

3. 環境をアクティブ化:

   • macOS/Linuxの場合:

     source .venv/bin/activate

   • Windowsの場合:

     GXP4 (プロンプトの前に

4. 依存関係のインストール: uvを使用して必要な Python パッケージをインストールします。

   uv pip install mcp httpx python-dotenv

   • mcp : モデルコンテキストプロトコル SDK。

   • httpx : SuzieQ API と通信するために使用される非同期 HTTP クライアント。

   • python-dotenv : 設定のために.envファイルから環境変数を読み込むために使用されます。

構成

サーバーにはSuzieQ APIエンドポイントとAPIキーが必要です。安全かつ簡単な設定のために、 .envファイルを使用してください。

1. .env プロジェクト ディレクトリのルート( main.pyと同じ場所) に、 .envという名前のファイルを作成します。

2. 認証情報の追加: SuzieQ エンドポイントとキーを.envファイルに追加します。キー/エンドポイント自体の一部でない限り、値が引用符で囲まれていないことを確認してください。

   # .env SUZIEQ_API_ENDPOINT=http://your-suzieq-host:8000/api/v2 SUZIEQ_API_KEY=your_actual_api_key

   プレースホルダーの値を実際のエンドポイントとキーに置き換えます。

3. **.envファイルのセキュリティ保護:**誤って秘密をコミットすることを防ぐために、 .gitignoreファイルに.envを追加します。

   echo ".env" >> .gitignore

4. **コード統合:**提供されたserver.py 、サーバーの起動時にpython-dotenvを使用してこれらの変数を自動的に読み込みます。

サーバーの実行

仮想環境が有効化されていることを確認してください。サーバーは現在のディレクトリにある.envファイルから設定を読み込みます。

1. 直接

ターミナルから直接サーバーを実行します。

サーバーが起動し、 Starting SuzieQ MCP Server... 」と表示され、標準入出力（stdio）でMCP接続を待機します。ツール経由でAPIクエリが正常に実行された場合、 [INFO]ログが表示されます。停止するにはCtrl+Cを押してください。

2. MCP Inspector（デバッグ用）

MCPインスペクターは、ツールを直接テストするのに便利です。mcp CLIツール（ uv pip install "mcp[cli]"経由）がインストールされている場合は、以下を実行してください。

対話型デバッガーが起動します。「ツール」タブに移動し、 run_suzieq_showを選択し、パラメータ（例：テーブル名：「device」）を入力して、「ツールを呼び出す」をクリックしてテストしてください。

Claude Desktopでの使用

シームレスに使用するためにサーバーを Claude Desktop と統合します。

1. Claude Desktop Config を見つけます。claude_desktop_config.jsonファイルを見つけclaude_desktop_config.json 。

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • ファイルと Claude ディレクトリが存在しない場合は作成します。

2. **設定ファイルの編集:**このサーバーのエントリを追加します。 main.pyへの絶対パスを使用してください。サーバーは.envからシークレットを読み込むため、この設定ファイルに含める必要はありません。

• /full/path/to/your/project/mcp-suzieq-server/main.pyをシステム上の正しい絶対パスに置き換えます。

• /full/path/to/your/project/mcp-suzieq-server/``main.pyと.envを含むディレクトリへの絶対パスに置き換えます。workingDirectory workingDirectory設定すると、 .envファイルが確実に見つかるようになります。

• Claude によってuvが見つからない場合は、 "uv"その絶対パスに置き換えます ( which uvまたはwhere uvで検索します)。

• Windows では、テキスト エンコードの問題が発生した場合"env": { "PYTHONUTF8": "1" }が必要になることがあります。

3. Claude Desktop を再起動します。Claude Desktop を完全に閉じて再度開きます。

4. 確認： Claude DesktopでMCPツールインジケーター（ハンマーアイコン🔨）を探します。クリックすると、 run_suzieq_showツールとrun_suzieq_summarizeツールの両方が表示されます。

ツールの使用法 (run_suzieq_show)

• table : (文字列、必須) SuzieQ テーブル名 (例: 「device」、「interface」、「bgp」)。

• フィルター: (辞書、オプション) フィルタリングに使用するキーと値のペア（例: "hostname": "leaf01" ）。フィルターを使用しない場合は省略するか、 {}を使用します。

• 戻り値: 結果またはエラーを含む JSON 文字列。

呼び出しの例（概念）:

すべてのデバイスを表示:

ホスト名「spine01」のBGPネイバーを表示します。

VRF 'default' で 'up' インターフェースを表示します。

ツールの使用状況 (run_suzieq_summarize)

• table : (文字列、必須) 要約する SuzieQ テーブル名 (例: "device"、"interface"、"bgp")。

• フィルター: (辞書、オプション) フィルタリングに使用するキーと値のペア（例: "hostname": "leaf01" ）。フィルターを使用しない場合は省略するか、 {}を使用します。

• 戻り値: 要約された結果またはエラーを含む JSON 文字列。

呼び出しの例（概念）:

すべてのデバイスを要約します。

ホスト名「spine01」別に BGP セッションを要約します。

VRF 'default' のインターフェース状態を要約します。

トラブルシューティング

エラー:「SuzieQ API エンドポイントまたはキーが設定されていません...」:

• .envファイルがmain.pyと同じディレクトリにあることを確認します。

• SUZIEQ_API_ENDPOINTとSUZIEQ_API_KEYが正しく入力されており、 .envに有効な値があることを確認します。

• Claude Desktop を使用する場合は、 claude_desktop_config.jsonのworkingDirectory``.envを含むディレクトリを指していることを確認してください。

HTTP エラー (4xx、5xx):

• SuzieQ API キー ( SUZIEQ_API_KEY ) が正しいことを確認します (401/403 エラー)。

• SUZIEQ_API_ENDPOINTが正しく、API サーバーが実行中であることを確認します。