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: 一个异步 HTTP 客户端，用于与 SuzieQ API 通信。
   • 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 Inspector 对于直接测试该工具非常有用。 如果您已安装 mcp CLI 工具（通过 uv pip install "mcp[cli]"），请运行：

uv run mcp dev main.py

这将启动一个交互式调试器。 转到“Tools”选项卡，选择 run_suzieq_show，输入参数（例如，table: "device"），然后单击“Call Tool”进行测试。

与 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": {
      // 如果 'uv' 在 Claude 使用的系统 PATH 中，则使用 'uv'，
      // 否则提供 uv 可执行文件的完整路径。
      "command": "uv",
      "args": [
        "run",
        "python",
        // --- 非常重要：使用下面的绝对路径 ---
        "/full/path/to/your/project/mcp-suzieq-server/main.py"
      ],
      // 如果 .env 在上面的项目目录中，则不需要 'env' 块
      "workingDirectory": "/full/path/to/your/project/mcp-suzieq-server/" // 可选，但推荐
    }
    // 如果需要，在此处添加其他服务器
  }
}

• 将 /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" }。

3. 重启 Claude Desktop: 完全关闭并重新打开 Claude Desktop。

4. 验证: 在 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"）。 省略或使用 {} 表示没有过滤器。
• Returns: 包含结果或错误的 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"）。 省略或使用 {} 表示没有过滤器。
• Returns: 包含汇总结果或错误的 JSON 字符串。

示例调用（概念性）：

汇总所有设备：

{ "table": "device" }

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

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

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

{ "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 服务器正在运行。