Skip to main content
Glama
SuzieQ MCP Server

SuzieQ MCP Server

by PovedaAqui

MCP Server for SuzieQ

This project provides a Model Context Protocol (MCP) server that allows language models and other MCP clients to interact with a SuzieQ network observability instance via its REST API.

Overview

The server exposes SuzieQ's commands as MCP tools:

  • run_suzieq_show: Access the 'show' command to query detailed network state tables

  • run_suzieq_summarize: Access the 'summarize' command to get aggregated statistics and summaries

These tools enable clients (like Claude Desktop) to query various network state tables (e.g., interfaces, BGP, routes) and apply filters, retrieving the results directly from your SuzieQ instance.

Related MCP server: OpsLevel MCP

Prerequisites

  • Python: Version 3.8 or higher is recommended.

  • uv: A fast Python package installer and resolver. (Installation guide)

  • SuzieQ Instance: A running SuzieQ instance with its REST API enabled and accessible.

  • SuzieQ API Endpoint & Key: You need the URL for the SuzieQ API (e.g., http://your-suzieq-host:8000/api/v2) and a valid API key (access_token).

Installation & Setup

Installing via Smithery

To install suzieq-mcp for Claude Desktop automatically via Smithery:

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

Installing Manually

  1. Get the Code: Clone this repository or download the main.py and server.py files into a dedicated project directory.

  2. Create Virtual Environment: Navigate to your project directory in the terminal and create a virtual environment using uv:

    uv venv
  3. Activate Environment:

    • On macOS/Linux:

      source .venv/bin/activate
    • On Windows:

      .venv\Scripts\activate

    (You should see (.venv) preceding your prompt)

  4. Install Dependencies: Install the required Python packages using uv:

    uv pip install mcp httpx python-dotenv
    • mcp: The Model Context Protocol SDK.

    • httpx: An asynchronous HTTP client used to communicate with the SuzieQ API.

    • python-dotenv: Used to load environment variables from a .env file for configuration.

Configuration

The server needs your SuzieQ API endpoint and API key. Use a .env file for secure and easy configuration:

  1. Create .env file: In the root of your project directory (the same place as main.py), create a file named .env.

  2. Add Credentials: Add your SuzieQ endpoint and key to the .env file. Ensure there are no quotes around the values unless they are part of the key/endpoint itself.

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

    Replace the placeholder values with your actual endpoint and key.

  3. Secure .env file: Add .env to your .gitignore file to prevent accidentally committing secrets.

    echo ".env" >> .gitignore
  4. Code Integration: The provided server.py automatically uses python-dotenv to load these variables when the server starts.

Running the Server

Make sure your virtual environment is activated. The server will load configuration from the .env file in the current directory.

1. Directly

Run the server directly from your terminal:

uv run python main.py

The server will start, print Starting SuzieQ MCP Server..., and listen for MCP connections on standard input/output (stdio). You should see [INFO] logs if it successfully queries the API via the tool. Press Ctrl+C to stop it.

2. With MCP Inspector (for Debugging)

The MCP Inspector is useful for testing the tool directly. If you have the mcp CLI tools installed (via uv pip install "mcp[cli]"), run:

uv run mcp dev main.py

This launches an interactive debugger. Go to the "Tools" tab, select run_suzieq_show, enter parameters (e.g., table: "device"), and click "Call Tool" to test.

Using with Claude Desktop

Integrate the server with Claude Desktop for seamless use:

  1. Find Claude Desktop Config: Locate the claude_desktop_config.json file.

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

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

    • Create the file and the Claude directory if they don't exist.

  2. Edit Config File: Add an entry for this server. Use the absolute path to main.py. The server loads secrets from .env, so they don't need to be in this config.

{
  "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
  }
}
  • Replace /full/path/to/your/project/mcp-suzieq-server/main.py with the correct absolute path on your system.

  • Replace /full/path/to/your/project/mcp-suzieq-server/ with the absolute path to the directory containing main.py and .env. Setting workingDirectory helps ensure the .env file is found.

  • If uv isn't found by Claude, replace "uv" with its absolute path (find via which uv or where uv).

  • On Windows, you might need "env": { "PYTHONUTF8": "1" } if you encounter text encoding issues.

  1. Restart Claude Desktop: Completely close and reopen Claude Desktop.

  2. Verify: Look for the MCP tool indicator (hammer icon 🔨) in Claude Desktop. Clicking it should show both the run_suzieq_show and run_suzieq_summarize tools.

Tool Usage (run_suzieq_show)

run_suzieq_show(table: str, filters: Optional[Dict[str, Any]] = None) -> str
  • table: (String, Required) The SuzieQ table name (e.g., "device", "interface", "bgp").

  • filters: (Dictionary, Optional) Key-value pairs for filtering (e.g., "hostname": "leaf01"). Omit or use {} for no filters.

  • Returns: A JSON string with the results or an error.

Example Invocations (Conceptual):

Show all devices:

{ "table": "device" }

Show BGP neighbors for hostname 'spine01':

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

Show 'up' interfaces in VRF 'default':

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

Tool Usage (run_suzieq_summarize)

run_suzieq_summarize(table: str, filters: Optional[Dict[str, Any]] = None) -> str
  • table: (String, Required) The SuzieQ table name to summarize (e.g., "device", "interface", "bgp").

  • filters: (Dictionary, Optional) Key-value pairs for filtering (e.g., "hostname": "leaf01"). Omit or use {} for no filters.

  • Returns: A JSON string with the summarized results or an error.

Example Invocations (Conceptual):

Summarize all devices:

{ "table": "device" }

Summarize BGP sessions by hostname 'spine01':

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

Summarize interface states in VRF 'default':

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

Troubleshooting

Error: "SuzieQ API endpoint or key not configured...":

  • Ensure the .env file is in the same directory as main.py.

  • Verify SUZIEQ_API_ENDPOINT and SUZIEQ_API_KEY are correctly spelled and have valid values in .env.

  • If using Claude Desktop, ensure the workingDirectory in claude_desktop_config.json points to the directory containing .env.

HTTP Errors (4xx, 5xx):

  • Check the SuzieQ API key (SUZIEQ_API_KEY) is correct (401/403 errors).

  • Verify the SUZIEQ_API_ENDPOINT is correct and the API server is running.

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.

Inputs: table (required), filters.

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.

Inputs: table (required), filters.

Tool Schema Changelog

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

Loading tool schema changelog…

    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.

    Related MCP Connectors

    Related MCP Servers