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手动安装
- 获取代码： 克隆此存储库或下载
main.py和server.py将文件放入专用项目目录。
- 创建虚拟环境： 导航到终端中的项目目录，并使用创建虚拟环境
uv:
uv venv- 激活环境：
- 在macOS/Linux上：
source .venv/bin/activate- 在Windows上：
.venv\Scripts\activate*（你应该看看 (.venv) 在您的提示之前）*
- 安装依赖关系： 使用以下命令安装所需的Python包
uv:
uv pip install mcp httpx python-dotenv- mcp：模型上下文协议SDK。 - httpx：用于与SuzieQ API通信的异步HTTP客户端。 - python-dotenv：用于从加载环境变量 .env 配置文件。
配置
服务器需要您的SuzieQ API端点和API密钥。使用 .env 用于安全和轻松配置的文件：
- 创建
.env文件： 在 项目目录的根目录 （同一个地方main.py)，创建一个名为的文件.env.
- 添加凭据： 将您的SuzieQ端点和密钥添加到
.env文件。 确保值周围没有引号，除非它们是键/端点本身的一部分。
# .env
SUZIEQ_API_ENDPOINT=http://your-suzieq-host:8000/api/v2
SUZIEQ_API_KEY=your_actual_api_key*将占位符值替换为实际的端点和键。*
- 安全
.env文件： 添加.env到你的.gitignore文件，以防止意外泄露机密。
echo ".env" >> .gitignore- 代码集成： 提供的
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集成，实现无缝使用：
- 查找Claude桌面配置： 找到
claude_desktop_config.json文件。
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json - 如果文件和Claude目录不存在，请创建它们。
- 编辑配置文件： 为此服务器添加一个条目。使用绝对路径
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" }如果您遇到文本编码问题。
- 重新启动克劳德桌面： 完全关闭并重新打开Claude Desktop。
- 验证： 查找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服务器正在运行。