SuzieQ MCP Server

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：

手动安装

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. 直接

直接从终端运行服务器：

服务器将启动，打印Starting SuzieQ MCP Server... ，并在标准输入/输出 (stdio) 上监听 MCP 连接。如果服务器成功通过该工具查询 API，您应该会看到[INFO]日志。按Ctrl+C停止服务器。

2. 使用 MCP Inspector（用于调试）

MCP 检查器对于直接测试该工具非常有用。如果您已安装 mcp CLI 工具（通过uv pip install "mcp[cli]" ），请运行：

这将启动一个交互式调试器。转到“工具”选项卡，选择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加载机密信息，因此它们不需要包含在该配置中。

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

3. **重新启动 Claude Desktop：**完全关闭并重新打开 Claude Desktop。
4. **验证：**在 Claude Desktop 中查找 MCP 工具指示器（锤子图标 🔨）。点击它应该会同时显示run_suzieq_show和run_suzieq_summarize工具。

工具使用（run_suzieq_show）

• 表：（字符串，必需）SuzieQ 表名称（例如，“设备”、“接口”、“bgp”）。
• filters ：（字典，可选）用于过滤的键值对（例如， "hostname": "leaf01" ）。省略或使用{}表示不使用过滤器。
• 返回：包含结果或错误的 JSON 字符串。

示例调用（概念）：

显示所有设备：

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

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

工具使用（run_suzieq_summarize）

• 表：（字符串，必需）要汇总的 SuzieQ 表名称（例如，“设备”、“接口”、“bgp”）。
• filters ：（字典，可选）用于过滤的键值对（例如， "hostname": "leaf01" ）。省略或使用{}表示不使用过滤器。
• 返回：包含汇总结果或错误的 JSON 字符串。

示例调用（概念）：

汇总所有设备：

按主机名“spine01”汇总 BGP 会话：

总结 VRF‘默认’中的接口状态：

故障排除

错误：“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 服务器是否正在运行。