Cisco NSO MCP Server

Cisco NSO MCP 服务

这是 Cisco NSO（Network Services Orchestrator） 的 Model Context Protocol（MCP）服务实现，可将 NSO 数据和操作作为 MCP 基元（工具、资源等）公开，供 兼容 MCP 的客户端 使用，从而通过自然语言交互实现 AI 驱动的网络自动化。

示例自定义客户端

什么是 MCP？

Model Context Protocol（MCP） 是一种开放协议，用于规范 AI 模型与外部工具和服务的交互方式。MCP 支持：

• 工具定义：以结构化方式定义 AI 模型可使用的工具
• 工具发现：让模型发现可用工具的机制
• 工具执行：模型调用工具并接收结果的标准化方法
• 上下文管理：在工具和模型之间高效传递上下文
• 框架无关：适用于多种 AI 框架，包括 OpenAI、Anthropic、Google Gemini 等
• 互操作性：为 AI 系统与外部工具通信提供通用语言

功能

• Stdio 传输：此 MCP 服务默认使用 stdio 传输进行进程绑定通信
• 工具优先设计：网络操作以接口清晰的独立工具形式定义
• 异步处理：所有网络操作均以异步方式实现，以提升性能
• 结构化响应：采用一致的响应格式，包含状态、数据和元数据部分
• 环境资源：提供有关 NSO 环境的上下文信息
• NSO 集成：使用 cisco-nso-restconf 库，以简洁、符合 Python 风格的接口访问 NSO 的 RESTCONF API
• 灵活日志记录：通过环境变量配置将日志输出到标准输出和／或文件。设置 LOG_FILE 环境变量后，日志会同时发送到标准输出和指定文件。如果无法创建或写入日志文件，服务会回退为仅向标准输出记录日志，并显示错误消息
• 支持多种客户端：可与任何兼容 MCP 的客户端配合使用，包括 Windsurf Cascade 和自定义 Python 应用

可用工具和资源

工具

工具名称	描述	输入	返回值
get_device_ned_ids	从 Cisco NSO 获取网络元素驱动程序（NED）ID		包含 NED ID 列表的字典
get_device_groups	从 Cisco NSO 获取设备组		包含设备组列表的字典
get_device_platform	获取 Cisco NSO 中特定设备的平台信息	'device_name'（字符串）	包含指定设备平台信息的字典
get_device_config	获取 Cisco NSO 中特定设备的完整配置	'device_name'（字符串）	包含指定设备配置的字典
get_device_state	获取 Cisco NSO 中特定设备的状态	'device_name'（字符串）	包含指定设备状态的字典
check_device_sync	检查 Cisco NSO 中特定设备的同步状态	'device_name'（字符串）	包含指定设备同步状态的字典
sync_from_device	在 Cisco NSO 中从特定设备同步	'device_name'（字符串）	包含指定设备同步状态的字典
get_service_types	获取 Cisco NSO 中的服务类型		包含服务类型的字典
get_services	获取 Cisco NSO 中特定服务类型的服务	'service_type'（字符串）	包含指定服务类型服务的字典

资源

• https://resources.cisco-nso-mcp.io/environment：提供 NSO 环境的精选摘要：
  • 设备数量、操作系统分布、操作系统种类数、型号种类数、型号分布、设备系列分布、设备组及其成员

要求

• Python 3.12+
• 启用了 RESTCONF API 的 Cisco NSO
• 与 NSO RESTCONF API 的网络连接

配置选项

你可以通过命令行参数或环境变量配置服务：

NSO 连接参数

命令行参数	环境变量	默认值	描述
--nso-scheme	NSO_SCHEME	http	NSO 连接协议（http/https）
--nso-address	NSO_ADDRESS	localhost	NSO 服务地址
--nso-port	NSO_PORT	8080	NSO 服务端口
--nso-timeout	NSO_TIMEOUT	10	连接超时时间（秒）
--nso-username	NSO_USERNAME	admin	NSO 用户名
--nso-password	NSO_PASSWORD	admin	NSO 密码
--nso-verify	NSO_VERIFY	True	验证 NSO HTTPS 证书（默认：True）。对于自签名证书（仅限开发环境），请使用 --no-nso-verify。
--nso-ca-bundle	NSO_CA_BUNDLE	None	用于信任 NSO HTTPS 的 CA 证书包文件路径。适用于 -nso-verify 为 True 的情况。

MCP 服务参数

命令行参数	环境变量	默认值	描述
--transport	MCP_TRANSPORT	stdio	MCP 传输类型（stdio/http）

HTTP 传输选项（仅在 --transport=http 时使用）

FastMCP HTTP Server reference: https://gofastmcp.com/deployment/http#http-deployment

Command-line Argument	Environment Variable	Default	Description
--host	MCP_HOST	0.0.0.0	Host to bind to when using HTTP transport
--port	MCP_PORT	8000	Port to bind to when using HTTP transport

Logging Configuration

Environment Variable	Default	Description
LOG_FILE	None	Path to log file. If not set, logs will be sent to stdout only

Environment variables take precedence over default values but are overridden by command-line arguments.

Connecting to the Server with MCP Clients

You can connect to the server using any MCP client that supports the selected transport type. A few options are:

Windsurf Cascade

Windsurf Cascade supports MCP servers through a configuration file. To use the Cisco NSO MCP server with Windsurf, add it to your mcp_config.json file.

Using uv (recommended)

When using uv, no specific installation is needed. You can use uvx to directly run the package:

{
  "mcpServers": {
    "nso": {
      "command": "uvx",
      "args": [
        "cisco-nso-mcp-server",
        "--nso-address=127.0.0.1",
        "--nso-port=8080",
        "--nso-username=admin",
        "--nso-password=admin"
      ],
      "env": {
        "LOG_FILE": "/path/to/your/logs/nso-mcp.log"
      }
    }
  }
}

使用 pip 安装

你也可以通过 pip 安装 cisco-nso-mcp-server：

pip install cisco-nso-mcp-server

现在你可以使用可执行文件的直接路径：

{
  "mcpServers": {
    "nso": {
      "command": "/path/to/your/env/bin/cisco-nso-mcp-server",
      "args": [
        "--nso-address=127.0.0.1",
        "--nso-port=8080",
        "--nso-username=admin",
        "--nso-password=admin"
      ],
      "env": {
        "LOG_FILE": "/path/to/your/logs/nso-mcp.log"
      }
    }
  }
}

将 /path/to/your/env/bin/cisco-nso-mcp-server 替换为你通过 pip 安装软件包时的实际路径。如果你将其安装在主环境中，可以运行 which cisco-nso-mcp-server 查找路径；也可以在虚拟环境的 bin 目录中查找。

无论哪种情况，env 部分都是可选的。如果包含该部分，你可以指定 LOG_FILE 环境变量以启用文件日志记录。

在使用 stdio 传输的自定义 MCP 客户端 Python 应用程序中使用

示例 Python 应用程序 sample_stdio_client.py 展示了如何在本地连接到 MCP 服务并执行工具。

作为独立程序运行服务

虽然该服务通常与 MCP 客户端配合使用，但你也可以将其直接作为独立进程运行：

# Run with default NSO connection and MCP settings (see Configuration Options above for details)
cisco-nso-mcp-server

# Run with custom NSO connection parameters
cisco-nso-mcp-server --nso-scheme=http --nso-address=127.0.0.1 --nso-port=8080 --nso-username=admin --nso-password=admin

使用 stdio 传输将服务作为独立进程运行时，你需要通过管道向进程传递输入/输出，或者使用支持 stdio 传输的 MCP 客户端。

许可证

本项目采用 MIT 许可证。这意味着你可以使用、修改和分发代码，但须遵守 MIT 许可证的条款和条件。