SuzieQ MCP Server

SuzieQ的MCP服务器

](https://smithery.ai/server/@PovedaAqui/suzieq-mcp)

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

概述

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

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

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

先决条件

• python 建议使用3.8或更高版本。
• 紫外线： 一个快速的Python包安装程序和解析器。 (安装指南)
• SuzieQ 实例 ： 一个正在运行的SuzieQ实例，其REST API已启用且可访问。
• SuzieQ API Endpoint & Key： 您需要SuzieQ API的URL（例如。， http://your-suzieq-host:8000/api/v2)和有效的API密钥(access_token).

安装和设置

通过Smithery安装

通过以下方式自动安装suzieq mcp for Claude Desktop 史密瑟里:

npx -y @smithery/cli install @PovedaAqui/suzieq-mcp --client claude

手动安装

1. 获取代码： 克隆此存储库或下载 main.py 和 server.py 将文件放入专用项目目录。

1. 创建虚拟环境： 导航到终端中的项目目录，并使用创建虚拟环境 uv:

   uv venv

1. 激活环境：

- 在macOS/Linux上：

     source .venv/bin/activate

- 在Windows上：

     .venv\Scripts\activate

*（你应该看看 (.venv) 在您的提示之前）*

1. 安装依赖关系： 使用以下命令安装所需的Python包 uv:

   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.

1. 添加凭据： 将您的SuzieQ端点和密钥添加到 .env 文件。 确保值周围没有引号，除非它们是键/端点本身的一部分。

   # .env
   SUZIEQ_API_ENDPOINT=http://your-suzieq-host:8000/api/v2
   SUZIEQ_API_KEY=your_actual_api_key

*将占位符值替换为实际的端点和键。*

1. 安全 .env 文件： 添加 .env 到你的 .gitignore 文件，以防止意外泄露机密。

   echo ".env" >> .gitignore

1. 代码集成： 提供的 server.py 自动使用 python-dotenv 在服务器启动时加载这些变量。

运行服务器

确保您的虚拟环境已激活。服务器将从加载配置 .env 当前目录中的文件。

1.直接

直接从终端运行服务器：

uv run python main.py

服务器将启动，打印 Starting SuzieQ MCP Server...，并监听标准输入/输出（stdio）上的MCP连接。你应该看看 [INFO] 如果通过该工具成功查询API，则记录。按 Ctrl+C 阻止它。

2.带MCP检查器（用于调试）

MCP检查器可用于直接测试工具。如果您安装了mcp CLI工具（通过 uv pip install "mcp[cli]")，运行：

uv run mcp dev main.py

这将启动一个交互式调试器。转到“工具”选项卡，选择 run_suzieq_show，输入参数（例如，表：“设备”），然后单击“调用工具”进行测试。

与Claude Desktop一起使用

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

1. 查找Claude桌面配置： 找到 claude_desktop_config.json 文件。

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - 如果文件和Claude目录不存在，请创建它们。

1. 编辑配置文件： 为此服务器添加一个条目。使用绝对路径 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" } 如果您遇到文本编码问题。

1. 重新启动克劳德桌面： 完全关闭并重新打开Claude Desktop。

1. 验证： 查找MCP工具指示灯（锤子图标🔨) 在克劳德桌面。点击它应该显示 run_suzieq_show 和 run_suzieq_summarize 工具。

工具用法（run_suzieq_show）

run_suzieq_show(table: str, filters: Optional[Dict[str, Any]] = None) -> str

• 桌子：（String，必选）SuzieQ表名（例如，“设备”、“接口”、“bgp”）。
• 过滤器：（字典，可选）用于过滤的键值对（例如。， "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

• 桌子：（String，必选）要汇总的SuzieQ表名（例如，“设备”、“接口”、“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，请确保 workingDirectory 在……里面 claude_desktop_config.json 指向包含以下内容的目录 .env.

HTTP错误（4xx，5xx）：

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