Skip to main content
Glama
Sign In
enesjakozh

SuzieQ MCP Server

by PovedaAqui
Verified
GitHub
Python
MIT License
2
  • Apple
  • Linux
RedditDiscord
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Integrations

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

SuzieQ 的 MCP 服务器

该项目提供了一个模型上下文协议 (MCP) 服务器，允许语言模型和其他 MCP 客户端通过其 REST API 与 SuzieQ 网络可观察性实例进行交互。

概述

服务器将 SuzieQ 的命令公开为 MCP 工具：

  • run_suzieq_show ：访问“show”命令来查询详细的网络状态表
  • run_suzieq_summarize ：访问“summarize”命令以获取汇总统计数据和摘要

这些工具使客户端（如 Claude Desktop）能够查询各种网络状态表（例如，接口、BGP、路由）并应用过滤器，直接从 SuzieQ 实例检索结果。

先决条件

  • **Python：**建议使用3.8或更高版本。
  • **uv：**一个快速的 Python 软件包安装程序和解析器。（安装指南）
  • **SuzieQ 实例：**正在运行的 SuzieQ 实例，其 REST API 已启用且可访问。
  • **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文件：**将.env添加到您的.gitignore文件中，以防止意外提交机密。
    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 ，输入参数（例如，table: "device"），然后点击“调用工具”进行测试。

与 Claude Desktop 一起使用

将服务器与 Claude Desktop 集成以实现无缝使用：

  1. **查找 Claude 桌面配置：**找到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有助于确保找到.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
  • 表：（字符串，必需）SuzieQ 表名称（例如，“设备”、“接口”、“bgp”）。
  • filters ：（字典，可选）用于过滤的键值对（例如， "hostname": "leaf01" ）。省略或使用{}表示不使用过滤器。
  • 返回：包含结果或错误的 JSON 字符串。

示例调用（概念）：

显示所有设备：

{ "table": "device" }

显示主机名“spine01”的 BGP 邻居：

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

显示 VRF‘默认’中的‘启动’接口：

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

工具使用（run_suzieq_summarize）

run_suzieq_summarize(table: str, filters: Optional[Dict[str, Any]] = None) -> str
  • 表：（字符串，必需）要汇总的 SuzieQ 表名称（例如，“设备”、“接口”、“bgp”）。
  • filters ：（字典，可选）用于过滤的键值对（例如， "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 服务器是否正在运行。

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

Tools

模型上下文协议 (MCP) 服务器允许语言模型和其他 MCP 客户端通过其 REST API 与 SuzieQ 网络可观察性实例进行交互。

  1. Overview
    1. Prerequisites
      1. Installation & Setup
        1. Installing via Smithery
        2. Installing Manually
      2. Configuration
        1. Running the Server
          1. 1. Directly
          2. 2. With MCP Inspector (for Debugging)
        2. Using with Claude Desktop
          1. Tool Usage (run_suzieq_show)
            1. Example Invocations (Conceptual):
          2. Tool Usage (run_suzieq_summarize)
            1. Example Invocations (Conceptual):
          3. Troubleshooting
            1. Error: "SuzieQ API endpoint or key not configured...":
            2. HTTP Errors (4xx, 5xx):

          Related Resources

          ID: rs1x5l381d