Skip to main content
Glama
enesjakozh
PovedaAqui

SuzieQ MCP Server

by PovedaAqui
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

SuzieQ 用 MCP サーバー

鍛冶屋のバッジ

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

概要

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

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

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

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

Related MCP server: OpsLevel MCP

前提条件

  • **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 を自動的にインストールするには:

npx -y @smithery/cli install @PovedaAqui/suzieq-mcp --client claude

手動でインストールする

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

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

    uv venv

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

    • macOS/Linuxの場合:

      source .venv/bin/activate

    • Windowsの場合:

      GXP4 (プロンプトの前に(.venv)が表示されます)

  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. 直接

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

uv run python main.py

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

2. MCP Inspector（デバッグ用）

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

uv run mcp dev main.py

対話型デバッガーが起動します。「ツール」タブに移動し、 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からシークレットを読み込むため、この設定ファイルに含める必要はありません。

{
  "mcpServers": {
    "suzieq-server": {
      // Use 'uv' if it's in the system PATH Claude uses,
      // otherwise provide the full path to the uv executable.
      "command": "uv",
      "args": [
        "run",
        "python",
        // --- VERY IMPORTANT: Use the ABSOLUTE path below ---
        "/full/path/to/your/project/mcp-suzieq-server/main.py"
      ],
      // 'env' block is not needed here if .env is in the project directory above
      "workingDirectory": "/full/path/to/your/project/mcp-suzieq-server/" // Optional, but recommended
    }
    // Add other servers here if needed
  }
}

  • /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" }が必要になることがあります。

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

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

ツールの使用法 (run_suzieq_show)

run_suzieq_show(table: str, filters: Optional[Dict[str, Any]] = None) -> str

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

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

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

呼び出しの例（概念）:

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

{ "table": "device" }

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

{ "table": "bgp", "filters": { "hostname": "spine01" } }

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

{ "table": "interface", "filters": { "vrf": "default", "state": "up" } }

ツールの使用状況 (run_suzieq_summarize)

run_suzieq_summarize(table: str, filters: Optional[Dict[str, Any]] = None) -> str

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

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

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

呼び出しの例（概念）:

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

{ "table": "device" }

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

{ "table": "bgp", "filters": { "hostname": "spine01" } }

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

{ "table": "interface", "filters": { "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 サーバーが実行中であることを確認します。

Available Tools

2 tools
run_suzieq_showA
Runs a SuzieQ 'show' query via its REST API.

Args:
    table: The name of the SuzieQ table to query (e.g., 'device', 'bgp', 'interface', 'route').
    filters: An optional dictionary of filter parameters for the SuzieQ query
             (e.g., {"hostname": "leaf01", "vrf": "default", "state": "Established"}).
             Keys should match SuzieQ filter names. Values can be strings or lists of strings.
             If no filters are needed, this can be None, null, or an empty dictionary.

Returns:
    A JSON string representing the result from the SuzieQ API, or a JSON string with an error message.
ParametersJSON Schema
NameRequiredDescriptionDefault
filtersNo
tableYes

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the REST API mechanism and error handling in returns, but doesn't cover important aspects like rate limits, authentication needs, timeout behavior, or what constitutes valid table names beyond examples. For a tool with no annotation coverage, this leaves significant gaps in understanding operational constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (Args, Returns) and uses bullet-like formatting for parameter details. While somewhat verbose, each sentence adds value by explaining parameter usage. The front-loaded purpose statement is clear, though some details could be more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no annotations, no output schema, and 2 parameters, the description does a good job with parameter semantics but lacks completeness in other areas. It doesn't explain the return structure beyond 'JSON string', doesn't cover error scenarios comprehensively, and omits behavioral constraints. For a query tool with REST API dependencies, more operational context would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by providing comprehensive parameter documentation. It clearly explains both parameters: 'table' with specific examples and 'filters' with detailed syntax, format examples, and handling of optional/null values. The description adds substantial meaning beyond what the bare schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Runs a SuzieQ show query') and mechanism ('via its REST API'), providing a specific verb+resource combination. It distinguishes from the sibling tool 'run_suzieq_summarize' by specifying this is for 'show' queries rather than 'summarize' operations, though it doesn't explicitly contrast them in the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through the examples of tables and filters, suggesting when to use this tool for querying network data. However, it lacks explicit guidance on when to choose this over 'run_suzieq_summarize' or other alternatives, and doesn't mention prerequisites like API connectivity or authentication requirements.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_suzieq_summarizeB
Runs a SuzieQ 'summarize' query via its REST API.

Args:
    table: The name of the SuzieQ table to summarize (e.g., 'device', 'bgp', 'interface', 'route').
    filters: An optional dictionary of filter parameters for the SuzieQ query
             (e.g., {"hostname": "leaf01", "vrf": "default"}).
             Keys should match SuzieQ filter names. Values can be strings or lists of strings.
             If no filters are needed, this can be None, null, or an empty dictionary.

Returns:
    A JSON string representing the summarized result from the SuzieQ API,
    or a JSON string with an error message.
ParametersJSON Schema
NameRequiredDescriptionDefault
filtersNo
tableYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the tool runs via REST API and returns JSON or error messages, but lacks details on authentication needs, rate limits, side effects, or what 'summarize' entails behaviorally (e.g., aggregation, statistics). This is a significant gap for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core purpose. The Args and Returns sections are structured clearly, though the 'filters' explanation is slightly verbose. Most sentences earn their place by adding value, with minimal redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters, no annotations, no output schema, and moderate complexity, the description covers purpose and parameters well but lacks behavioral context and explicit usage guidelines. It is adequate as a minimum viable description but has clear gaps in transparency and guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It effectively adds meaning by explaining 'table' as the SuzieQ table name with examples and 'filters' as an optional dictionary with examples and usage notes. This goes beyond the schema's minimal titles, providing practical context for both parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'runs a SuzieQ summarize query via its REST API', specifying the verb (runs), resource (SuzieQ summarize query), and mechanism (REST API). It distinguishes from the sibling tool 'run_suzieq_show' by focusing on 'summarize' queries rather than 'show' queries, though the distinction could be more explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for SuzieQ summarize queries but does not explicitly state when to use this tool versus the sibling 'run_suzieq_show' or other alternatives. It provides context about the REST API mechanism but lacks explicit guidance on scenarios or prerequisites for choosing this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedrun_suzieq_show
    • First observedrun_suzieq_summarize
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: run_suzieq_show performs a 'show' query to retrieve data, while run_suzieq_summarize performs a 'summarize' query to aggregate data. Their descriptions explicitly differentiate between querying and summarizing operations, leaving no ambiguity about which tool to use for each task.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with 'run_suzieq_' as a prefix, followed by the specific operation ('show' or 'summarize'). This naming convention is predictable and helps users understand the tools' functions at a glance, with no deviations or mixed styles.

Tool Count2/5

With only two tools, the server feels thin for its apparent scope of network monitoring and analysis via SuzieQ. While the tools cover basic query and summarize operations, the domain suggests a need for more comprehensive functionality, such as additional query types or data manipulation tools, making the count insufficient for robust agent workflows.

Completeness2/5

The tool surface is severely incomplete for network monitoring and analysis. It lacks essential operations like data filtering beyond basic queries, configuration management, or integration with other network tools. The two tools provide only a minimal subset of what a full SuzieQ interface would offer, leaving significant gaps that will hinder agent effectiveness.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers