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 上：

     .venv\Scripts\activate
     

   (您应该会看到 (.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 检查器（用于调试）

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 Desktop 配置文件： 找到 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，请将其替换为绝对路径（通过 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

• table: (字符串，必需) SuzieQ 表名称（例如："device"、"interface"、"bgp"）。
• filters: (字典，可选) 用于过滤的键值对（例如："hostname": "leaf01"）。不使用过滤器时可以省略或使用 {}。
• 返回值: 包含结果或错误的 JSON 字符串。

示例调用（概念性）：

显示所有设备：

{ "table": "device" }

显示主机名为 'spine01' 的 BGP 邻居：

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

显示 VRF 'default' 中状态为 '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"）。
• filters: (字典，可选) 用于过滤的键值对（例如："hostname": "leaf01"）。不使用过滤器时可以省略或使用 {}。
• 返回值: 包含汇总结果或错误的 JSON 字符串。

示例调用（概念性）：

汇总所有设备：

{ "table": "device" }

按主机名 'spine01' 汇总 BGP 会话：

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

汇总 VRF 'default' 中的接口状态：

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

故障排除

错误：“SuzieQ API 端点或密钥未配置...”：

• 确保 .env 文件与 main.py 在同一目录中。
• 验证 .env 文件中的 SUZIEQ_API_ENDPOINT 和 SUZIEQ_API_KEY 拼写正确且具有有效值。
• 如果使用 Claude Desktop，请确保 claude_desktop_config.json 中的 workingDirectory 指向包含 .env 文件的目录。

HTTP 错误 (4xx, 5xx)：

• 检查 SuzieQ API 密钥 (SUZIEQ_API_KEY) 是否正确（401/403 错误）。
• 验证 SUZIEQ_API_ENDPOINT 是否正确并且 API 服务器正在运行。