SuzieQ MCP 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_showto retrieve detailed information from specific tables like devices, interfaces, BGP, or routes.Summarize Data: Utilize
run_suzieq_summarizeto 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.
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.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
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 tablesrun_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 claudeInstalling Manually
Get the Code: Clone this repository or download the
main.pyandserver.pyfiles into a dedicated project directory.Create Virtual Environment: Navigate to your project directory in the terminal and create a virtual environment using
uv:uv venvActivate Environment:
On macOS/Linux:
source .venv/bin/activateOn 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-dotenvmcp: 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.envfile for configuration.
Configuration
The server needs your SuzieQ API endpoint and API key. Use a .env file for secure and easy configuration:
Create
.envfile: In the root of your project directory (the same place asmain.py), create a file named.env.Add Credentials: Add your SuzieQ endpoint and key to the
.envfile. 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_keyReplace the placeholder values with your actual endpoint and key.
Secure
.envfile: Add.envto your.gitignorefile to prevent accidentally committing secrets.echo ".env" >> .gitignoreCode Integration: The provided
server.pyautomatically usespython-dotenvto 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.pyThe 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.pyThis 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.jsonfile.macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonCreate 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.pywith the correct absolute path on your system.Replace
/full/path/to/your/project/mcp-suzieq-server/with the absolute path to the directory containingmain.pyand.env. SettingworkingDirectoryhelps ensure the.envfile is found.If
uvisn't found by Claude, replace"uv"with its absolute path (find viawhich uvorwhere 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_showandrun_suzieq_summarizetools.
Tool Usage (run_suzieq_show)
run_suzieq_show(table: str, filters: Optional[Dict[str, Any]] = None) -> strtable: (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) -> strtable: (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
.envfile is in the same directory asmain.py.Verify
SUZIEQ_API_ENDPOINTandSUZIEQ_API_KEYare correctly spelled and have valid values in.env.If using Claude Desktop, ensure the
workingDirectoryinclaude_desktop_config.jsonpoints 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_ENDPOINTis correct and the API server is running.
Available Tools
2 toolsrun_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
Scored across 2 tools
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.
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.
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.
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
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
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
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server designed to easily dump your codebase context into Large Language Models (LLMs).18 npm3Apache 2.0

OpsLevel MCPofficial
AlicenseNot gradedqualityFmaintenanceModel Context Protocol (MCP) server for OpsLevel12MIT- AlicenseBqualityCmaintenanceA 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.51MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol (MCP) server for interacting with Nautobot APIs using semantic search and dynamic API requests.16MIT