en es ja ko zh

SuzieQ MCP Server

Name: SuzieQ MCP Server
Author: PovedaAqui

by PovedaAqui

Overview Schema Source Related Servers Discussions Admin

Python

Remote

SuzieQ용 MCP 서버

대장간 배지

이 프로젝트는 언어 모델과 다른 MCP 클라이언트가 REST API를 통해 SuzieQ 네트워크 관찰 인스턴스와 상호 작용할 수 있도록 하는 MCP(Model Context Protocol) 서버를 제공합니다.

개요

서버는 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를 자동으로 설치하려면:

지엑스피1

수동 설치

코드 가져오기: 이 저장소를 복제하거나 main.py 및 server.py 파일을 전용 프로젝트 디렉토리에 다운로드하세요.
가상 환경 만들기: 터미널에서 프로젝트 디렉토리로 이동하고 uv 사용하여 가상 환경을 만듭니다.
```
uv venv
```
환경 활성화:
- macOS/Linux의 경우:
  source .venv/bin/activate
- Windows의 경우:
  GXP4 (프롬프트 앞에 (.venv) 가 표시되어야 함)
종속성 설치: uv 사용하여 필요한 Python 패키지를 설치합니다.
```
uv pip install mcp httpx python-dotenv
```
- mcp : 모델 컨텍스트 프로토콜 SDK.
- httpx : SuzieQ API와 통신하는 데 사용되는 비동기 HTTP 클라이언트입니다.
- python-dotenv : 구성을 위해 .env 파일에서 환경 변수를 로드하는 데 사용됩니다.

구성

서버에는 SuzieQ API 엔드포인트와 API 키가 필요합니다. 안전하고 간편한 설정을 위해 .env 파일을 사용하세요.

.env 파일을 만듭니다. 프로젝트 디렉토리의 루트 ( main.py 와 같은 위치)에 .env 라는 이름의 파일을 만듭니다.
자격 증명 추가: SuzieQ 엔드포인트와 키를 .env 파일에 추가합니다. 키/엔드포인트 자체에 포함된 경우를 제외하고 값을 따옴표로 묶지 마십시오.
```
# .env
SUZIEQ_API_ENDPOINT=http://your-suzieq-host:8000/api/v2
SUZIEQ_API_KEY=your_actual_api_key
```
플레이스홀더 값을 실제 엔드포인트와 키로 바꾸세요.
.env 파일 보안: .gitignore 파일에 .env 추가하여 실수로 기밀을 커밋하는 것을 방지합니다.
```
echo ".env" >> .gitignore
```
코드 통합: 제공된 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 Inspector는 도구를 직접 테스트하는 데 유용합니다. mcp CLI 도구가 설치되어 있는 경우( uv pip install "mcp[cli]" ) 다음을 실행하세요.

uv run mcp dev main.py

대화형 디버거가 실행됩니다. "도구" 탭으로 이동하여 run_suzieq_show 선택하고 매개변수(예: table: "device")를 입력한 후 "도구 호출"을 클릭하여 테스트하세요.

Claude Desktop과 함께 사용

원활한 사용을 위해 Claude Desktop과 서버를 통합하세요.

Claude Desktop Config 찾기: claude_desktop_config.json 파일을 찾습니다.
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- 해당 파일과 Claude 디렉토리가 없으면 새로 만듭니다.
구성 파일 편집: 이 서버에 대한 항목을 추가하세요. 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 설정하면 .env 파일을 찾을 수 있습니다.
클로드가 uv 찾지 못하면 "uv" 절대 경로로 바꿉니다( which uv 또는 where uv 통해 찾을 수 있음).
Windows에서 텍스트 인코딩 문제가 발생하면 "env": { "PYTHONUTF8": "1" } 필요할 수 있습니다.

Claude Desktop을 다시 시작합니다. Claude Desktop을 완전히 닫았다가 다시 엽니다.
확인: 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 '기본'에서 '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 '기본'에서 인터페이스 상태를 요약합니다.

{ "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

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
6 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 3 months ago (2026-07-10 16:15 UTC)
12
MIT
MCP Nautobot Server
aiopnet
A
license
B
quality
C
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 12 days ago (2026-09-27 09:21 UTC)
5
1
MIT
nautobot_mcp
Networking & Infrastructure RAG Systems Developer Tools
kvncampos
A
license
Not graded
quality
D
maintenance
A Model Context Protocol (MCP) server for interacting with Nautobot APIs using semantic search and dynamic API requests.
Updated 6 months ago (2026-04-15 23:14 UTC)
17
MIT

SuzieQ용 MCP 서버

개요

필수 조건

설치 및 설정

Smithery를 통해 설치

수동 설치

구성

서버 실행

1. 직접

2. MCP Inspector 사용(디버깅용)

Claude Desktop과 함께 사용

도구 사용(run_suzieq_show)

예시 호출(개념적):

도구 사용(run_suzieq_summarize)

예시 호출(개념적):

문제 해결

오류: "SuzieQ API 엔드포인트 또는 키가 구성되지 않았습니다...":

HTTP 오류(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