What can you do with this server?

The SuzieQ MCP Server enables interaction with a SuzieQ network observability instance via its REST API, providing tools to query and summarize network state data. * Query Network State: Use run_suzieq_show to retrieve detailed information from specific tables like devices, interfaces, BGP, or routes. * Summarize Data: Utilize run_suzieq_summarize to obtain aggregated statistics and summaries from network state tables. * Apply Filters: Both tools support filtering results based on criteria like hostname, VRF, or state using key-value pairs. * JSON Output: Results are returned as JSON strings for easy programmatic processing. * Integration: Seamlessly use these capabilities within Claude Desktop and other MCP clients for streamlined network analysis.

Which integrations are available for this server?

Used for loading environment variables from a .env file to securely store and access the SuzieQ API endpoint and access token. Serves as the runtime environment for the MCP server, with version 3.8 or higher recommended.

How do I use SuzieQ MCP Server?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@SuzieQ MCP Server show me the status of all interfaces on router core-01" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

en es ja ko zh

SuzieQ MCP Server

by PovedaAqui

Overview Schema Source Related Servers Discussions Admin

Python

Remote

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

Get the Code: Clone this repository or download the main.py and server.py files into a dedicated project directory.
Create Virtual Environment: Navigate to your project directory in the terminal and create a virtual environment using uv:
```
uv venv
```
Activate Environment:
- On macOS/Linux:
  source .venv/bin/activate
- On Windows:
  .venv\Scripts\activate
(You should see (.venv) preceding your prompt)
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:

Create .env file: In the root of your project directory (the same place as main.py), create a file named .env.
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.
Secure .env file: Add .env to your .gitignore file to prevent accidentally committing secrets.
```
echo ".env" >> .gitignore
```
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:

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

Restart Claude Desktop: Completely close and reopen Claude Desktop.
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.

ParametersJSON Schema

Name	Required	Description	Default
`filters`	No
`table`	Yes

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

Name	Required	Description	Default
`filters`	No
`table`	Yes

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.

2 tool updatesv1.0.0Aug 18, 2025
- 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 2026-04-18 10:35 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

GitHub Repository

Need Help?

Reddit Discussion

Related Servers

Related MCP Connectors

jumpcloud-genaiOAuth
com.jumpcloud
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Cloud Platforms Security Developer Tools
2
hithereiamaliff-mcp-nextcloudOAuth
ai.smithery
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Cloud Storage File Systems Workplace & Productivity
238
Apideck MCP A
dev.apideck.mcp
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
Developer Tools
42
mcp AOAuth
io.scorecard
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
RAG Systems Monitoring Testing & QA Tools
3

Related MCP Servers

@lex-tools/codebase-contextofficial
Code Analysis Developer Tools Documentation Access
lex-tools
A
license
A
quality
D
maintenance
A Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).
Updated a year ago (2025-08-02 06:43 UTC)
1
3 npm
3
Apache 2.0
OpsLevel MCPofficial
Developer Tools Observability Monitoring
OpsLevel
A
license
Not graded
quality
F
maintenance
Model Context Protocol (MCP) server for OpsLevel
Updated 2 months ago (2026-07-10 16:15 UTC)
12
MIT
MCP Nautobot Server
aiopnet
A
license
B
quality
D
maintenance
A Model Context Protocol server that integrates with Nautobot to provide network automation and infrastructure data to AI assistants like Claude, allowing them to query and interact with network Source of Truth systems.
Updated a year ago (2025-07-12 16:16 UTC)
5
1
MIT
nautobot_mcp
Networking & Infrastructure RAG Systems Developer Tools
kvncampos
A
license
Not graded
quality
C
maintenance
A Model Context Protocol (MCP) server for interacting with Nautobot APIs using semantic search and dynamic API requests.
Updated 5 months ago (2026-04-15 23:14 UTC)
16
MIT

MCP Server for SuzieQ

Overview

Prerequisites

Installation & Setup

Installing via Smithery

Installing Manually

Configuration

Running the Server

1. Directly

2. With MCP Inspector (for Debugging)

Using with Claude Desktop

Tool Usage (run_suzieq_show)

Example Invocations (Conceptual):

Tool Usage (run_suzieq_summarize)

Example Invocations (Conceptual):

Troubleshooting

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

HTTP Errors (4xx, 5xx):

Available Tools

TDQS

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

@lex-tools/codebase-contextofficial

OpsLevel MCPofficial

MCP Nautobot Server

nautobot_mcp