Junos MCP

junos-mcp

English | 日本語

面向 junos-ops 的 MCP（Model Context Protocol）服务。

通过 STDIO 传输方式，向兼容 MCP 的 AI 助手（Claude Desktop、Claude Code、OpenAI Codex 等）提供 Juniper Networks 设备操作能力。 junos-ops 是供人类使用的命令行工具，而 junos-mcp 则是面向 AI 的接口，使用同一强大的引擎。

功能

设备信息

工具	描述	连接
get_device_facts	获取设备基本信息（型号、主机名、序列号、版本）	是
get_version	获取 JUNOS 版本及升级状态	是
get_router_list	列出 config.ini 中的路由器（可按标签筛选）	否
health_check	报告服务版本和配置状态（路由器数量、不同标签数）。轻量级；不会连接任何设备	否

CLI 命令执行

工具	描述	连接
run_show_command	运行单条 CLI show 命令（output_format：text/json/xml）	是
run_show_commands	在单个会话中运行多条 CLI 命令（output_format：text/json/xml）	是
run_show_command_batch	并行在多台设备上运行命令（支持标签筛选和 grep_pattern）	是

配置管理

工具	描述	连接
get_config	获取设备配置（text/set/xml 格式）	是
get_config_diff	显示与回滚版本相比的配置差异	是
push_config	推送配置，使用 commit confirmed 并执行健康检查	是
push_config_start / push_config_result	将相同的配置推送作为后台任务运行，适用于约 60 秒后会中断调用的托管客户端，以及提交较慢的型号（SRX 分支）：push_config_start 会返回差异和 job_id，不等待提交完成；提交将在同一个已锁定会话中执行。轮询 push_config_result，直到其状态不再为 running	是

升级操作

工具	描述	连接
check_upgrade_readiness	检查设备是否已准备好升级	是
compare_version	比较两个 JUNOS 版本字符串	否
get_package_info	获取特定型号的软件包文件及哈希值	否
list_remote_files	列出远程设备路径上的文件	是
copy_package	通过 SCP 复制固件包并校验校验和	是
install_package	执行安装前检查后安装固件（EX2300/EX3400 使用 unlink 标志）	是
rollback_package	回滚到之前的软件包版本	是
schedule_reboot	将设备重启安排在指定时间	是

诊断

工具	描述	连接
collect_rsi	使用特定型号的超时设置收集 RSI/SCF	是
collect_rsi_batch	并行从多台设备收集 RSI/SCF（支持标签筛选）	是

安装前检查

等同于 junos-ops check 子命令的各模式。三种模式都会复用 junos-ops 显示层来渲染表格。

工具	描述	连接
check_reachability	检测每台主机的 NETCONF 可达性和可用磁盘空间（速度快：不获取设备信息，使用 5 秒 TCP 探测）	是
check_local_inventory	根据 config.ini 清单校验本地固件校验和	否
check_remote_packages	校验设备上已暂存固件的校验和及可用磁盘空间（SCP 后校验）	是

日常运维

工具	描述	连接
daily_brief	并行检查多台设备的晨间健康状况：警报、接口状态、回溯时间窗口内的 syslog 告警模式（since_hours，默认 18 h）、双 RE 故障（[RE_FAULT]；SRX 机箱集群会跳过此项，因为其事实信息会错误报告 RE 状态——集群节点故障会通过机箱警报显现），以及可选的 inet.0 路由数量基线（route_baseline，例如 tags=["main"], route_baseline=152）。返回 CRITICAL/WARNING/OK Markdown 摘要。	是
daily_brief_start / daily_brief_result	对规模过大、无法在一次调用中完成的设备群，以后台任务运行相同的检查（托管客户端每次调用的时限约为 60 s）：daily_brief_start 会立即返回 job_id，然后轮询 daily_brief_result，直到状态为 done。同步的 daily_brief 现在会在 JUNOS_DEADLINE 秒后停止（默认 45；0 表示禁用），并在 NOT CHECKED 下列出尚未完成检查的主机。	是

安全设计

所有具有破坏性的操作（push_config、copy_package、install_package、 rollback_package、schedule_reboot）默认均为演练模式（dry_run=True）。 AI 助手必须显式设置 dry_run=False 才会进行更改。

push_config 提供了其他 Junos MCP 服务不具备的额外安全功能：

• commit confirmed，超时时间可配置（若未确认则自动回滚）
• 提交后的备用健康检查（ping、NETCONF 运行时间探测或任意 CLI 命令）
• 健康检查失败时自动回滚（提交不会被确认，计时器到期后回滚）
• no_commit=True —— 发出 commit confirmed，但有意跳过最终提交。 JUNOS 会在 confirm_timeout 分钟后自动回滚。适用于重启没有 request ...restart 命令的服务（例如 EX3400 升级后重启 syslog 守护进程）。

RPC 超时与单次调用时限。 每个 load/commit RPC 都使用主机 config.ini 配置段中的 timeout；若未设置，则使用 junos-ops 模型的 默认值：SRX 分支型号（SRX300/320/340/345 等，其提交可能超过 30 s）为 180 s，其他型号为 120 s。该超时不会缩短。设置了 JUNOS_DEADLINE （默认 45 s；0 表示禁用）时，push_config 会将推送作为后台任务运行，并 等待至距离时限到期不久：如果任务完成，返回结果与未设置时限时相同；若未完成， 则返回 Still running，并提供可用于轮询 push_config_result 的 job_id。 push_config_start 会返回差异和 job_id，而不等待提交；该任务会在同一锁定 会话中加载并比较更改，然后提交，因此实际提交的内容与返回的差异完全一致。 发送 commit confirmed 后发生的故障会报告为可能仍待确认的提交，并会在 confirm_timeout 分钟后由设备回滚。每台主机同一时间只运行一个推送任务； 第二个推送会被拒绝，而该主机上的其他工具最多等待至时限到期，然后返回 host busy。

要求

• Python 3.12+
• junos-ops，并配置有效的 config.ini
• MCP Python SDK >= 1.0

安装

pip install junos-mcp

或用于开发：

git clone https://github.com/shigechika/junos-mcp.git
cd junos-mcp
python3 -m venv .venv
. .venv/bin/activate
pip install -e ".[test]"

CLI 选项

python -m junos_mcp --help

选项	描述
-V、--version	打印版本并退出
--check	加载 config.ini、列出路由器并退出（出错时退出码为 1）
--check-host HOSTNAME	与 --check 搭配使用时，还会打开 NETCONF 会话以验证可达性和身份验证
--transport {stdio,streamable-http}	传输协议（默认值：stdio）
--host HOST / --port PORT	仅用于 streamable-http：要监听的地址和端口（默认值：127.0.0.1 / 8000）。请使用这些选项，而不是 FASTMCP_HOST / FASTMCP_PORT；MCP Python SDK 2.x 已不再读取这两个环境变量

在将服务注册到 AI 助手之前，使用 --check 可以方便地验证 JUNOS_OPS_CONFIG 和 config.ini 是否可访问。搭配 --check-host rt1 使用，还可确认凭据能否通过真实设备的身份验证。

基于标签的主机筛选

run_show_command_batch、collect_rsi_batch 和 get_router_list 接受可选的 tags 参数。其语法与 junos-ops 的 --tags CLI 标志一致（自 junos-mcp 0.9.0 / junos-ops 0.16.6 起）：

• 列表中的每个元素都是一个标签组。组内以逗号分隔的标签按 AND 关系组合。
• 多个列表元素之间按 OR 关系匹配。
• 与批处理工具中的 hostnames 组合时，结果为交集（先按标签筛选，再按名称进一步缩小范围）。交集为空时会返回错误。

# 1 group, 1 tag — hosts tagged "main"
run_show_command_batch(command="show route summary", tags=["main"])

# 1 group, 2 tags — AND within the group: tokyo AND edge
collect_rsi_batch(tags=["tokyo,edge"])

# 2 groups — OR across groups: main OR backup
get_router_list(tags=["main", "backup"])

# Mixed: (tokyo AND core) OR backup
run_show_command_batch(command="show version", tags=["tokyo,core", "backup"])

# Intersection: among backup-tagged hosts, only rt1/rt2
run_show_command_batch(
    command="show version",
    hostnames=["rt1.example.jp", "rt2.example.jp"],
    tags=["backup"],
)

有关如何在 config.ini 中为区段添加标签以及匹配用的 CLI 语法，请参阅 junos-ops 标签文档。

结构化输出格式

run_show_command 和 run_show_commands 接受可选的 output_format 参数：

值	描述
"text"	默认值。纯文本 CLI 输出（与输入命令后得到的输出相同）
"json"	NETCONF JSON 输出——设备返回结构化字典
"xml"	NETCONF XML 输出——设备返回格式化后的 XML

注意： 无论 output_format 的值是什么，CLI 管道阶段（| match、| last、| count 等）都会被静默丢弃。PyEZ 的 Device.cli() 通过 NETCONF RPC 发送命令，而 JunOS 不会对其进行管道处理。请在不使用管道的情况下运行命令，然后在客户端进行筛选。对于单条命令，run_show_command_batch 的 grep_pattern 参数（见下文）可提供类似服务端的筛选功能——即使只有一台主机，也可以通过传入仅含一个元素的 hostnames 列表来实现。不过，它在内部始终获取纯文本输出（不能与 output_format="json" / "xml" 搭配使用），且一次只能接受一条命令，因此无法直接替代 run_show_commands 的多命令用法。

# Get structured BGP summary data
run_show_command("router-a", "show bgp summary", output_format="json")

服务端输出筛选

run_show_command_batch 接受可选的 grep_pattern 参数（Python re 模式）。设置该参数后，每台主机的输出中只会保留匹配的行。标题行（以 # 开头）始终会保留。没有匹配行的主机会显示 (no match)。

此功能可缩减大型批处理结果——例如，93 台路由器 × show route summary——将数百 KB 的结果压缩到几百字节，只提取相关行：

# Extract only the inet.0 destination count from 93 routers
run_show_command_batch(
    command="show route summary",
    tags=["main"],
    grep_pattern=r"inet\.0:\s+\d+ destinations",
)

连接池

junos-mcp 为每台主机维护一个 NETCONF 连接池。复用空闲的 Device 可避免每次调用工具时都进行 TCP/NETCONF 握手；连接池通过每台主机各自的锁， 串行处理同一主机上的并发操作。

环境变量	默认值	说明
JUNOS_MCP_POOL	1（启用）	设置为 0 可禁用连接池，每次调用时都新建连接
JUNOS_MCP_POOL_IDLE	60	空闲超时时间，单位为秒。连接闲置时间超过此值后，会在下次调用时关闭。设置为 0 可禁用过期清理

**安全说明：**池中的连接是长期运行的 SSH 会话。如果策略限制了会话持续时间，请将 JUNOS_MCP_POOL_IDLE 设为短于不活动时限的值，或设置 JUNOS_MCP_POOL=0 以完全禁用连接池。

配置

此服务使用与 junos-ops 相同的 config.ini。详情请参阅 junos-ops README。

每个工具都接受可选的 config_path 参数。如果省略，则按以下顺序查找：

1. 环境变量 JUNOS_OPS_CONFIG
2. ./config.ini
3. ~/.config/junos-ops/config.ini

实际上，config.ini 是必需的：每个工具——包括不会打开设备连接的 get_router_list 和 health_check——都会在启动时读取该文件；如果找不到文件，程序不会以降级模式继续运行。在将服务注册到任何 MCP 客户端之前，请先在上述三个位置之一放置可用的 config.ini。

写入操作

五个工具会更改设备状态。其余工具都只读取信息。这五个工具默认都采用 dry_run=True——关于试运行和确认后提交的机制，请参阅安全设计；此表说明各工具调用的内容及设备侧所需的权限。

工具	API 调用	权限要求
push_config（及其后台形式 push_config_start）	jnpr.junos.utils.config.Config：lock → load(format="set") → diff → commit_check → commit(confirm=confirm_timeout) → 健康检查 → 最终 commit → unlock	config.ini 中用于目标主机的账户必须具有允许进入配置模式并执行提交操作的 JUNOS 登录类，而非只读／操作员类。具体类名取决于在 config.ini 中为每台设备配置的内容。
copy_package	junos_ops.upgrade.copy()——将固件包通过 SCP 复制到设备，并验证校验和、在复制前清理存储空间	同一账户还需具有文件复制／存储写入权限（可通过 SCP 写入设备闪存）。
install_package	junos_ops.upgrade.install()——版本检查、待回滚检查、复制并验证校验和、清除重启计划、保存救援配置，然后调用 PyEZ SW.install()（或在低闪存 EX2300/EX3400 上通过 unlink CLI 路径执行 request system software add）	需要软件安装权限——JUNOS maintenance 类或超级用户登录类。
rollback_package	junos_ops.upgrade.rollback()——相当于执行 request system software rollback，仅在确认存在待回滚版本后才执行	需要与 install_package 相同的高权限软件维护权限。
schedule_reboot	计划执行 request system reboot at <time>	需要设备上的重启／维护权限。

如果为某台主机的 config.ini 账户配置只读／操作员登录类，这五个工具在该主机上都会因权限错误而失败；其他所有工具——show 命令、配置读取、诊断、daily_brief——仍可正常工作。对此没有单独的插件级开关：权限边界完全由分配给 config.ini 账户的 JUNOS 登录类决定。

用法

Claude Code（插件）

此仓库同时也是一个仅包含单个插件的市场，因此 Claude Code 可以为你安装该服务：

/plugin marketplace add shigechika/junos-mcp
/plugin install junos-mcp@junos-mcp

该插件会启动 uvx junos-mcp，并读取配置中所述的相同环境变量；启动 Claude Code 前，请导出 JUNOS_OPS_CONFIG（或将 config.ini 放在 ./config.ini 或 ~/.config/junos-ops/config.ini）。

运行 Claude Code 的进程必须能在 PATH 中找到 uvx——登录 Shell 通常已包含它，但通过 GUI 启动的应用可能没有；如果插件无法启动，请安装系统级的 uv。

Claude Code（手动）

使用 claude mcp add 注册 MCP 服务：

claude mcp add junos-mcp \
  -e JUNOS_OPS_CONFIG=~/.config/junos-ops/config.ini \
  -- python -m junos_mcp

--scope（-s）选项用于控制配置的存储位置：

范围	描述	配置位置
local（默认）	当前项目，仅当前用户可用	~/.claude.json
project	当前项目，与团队共享	项目根目录中的 .mcp.json
user	所有项目，仅当前用户可用	~/.claude.json

Claude Desktop

将以下内容添加到 Claude Desktop 配置文件中：

操作系统	配置文件
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "junos-mcp": {
      "command": "python",
      "args": ["-m", "junos_mcp"],
      "env": {
        "JUNOS_OPS_CONFIG": "/path/to/config.ini"
      }
    }
  }
}

编辑后重新启动 Claude Desktop。

Codex

使用 codex mcp add 注册 MCP 服务：

codex mcp add junos-mcp \
  --env JUNOS_OPS_CONFIG=~/.config/junos-ops/config.ini \
  -- python -m junos_mcp

任何其他可启动 stdio 服务的 MCP 客户端也可采用相同方式：将 python -m junos_mcp 设为命令，并在其环境中设置 JUNOS_OPS_CONFIG。

使用 OAuth 远程访问（通过 mcp-stdio）

junos-mcp 支持 Streamable HTTP 传输，可通过 mcp-stdio 作为 OAuth 代理，从任何 MCP 客户端（Claude Desktop、Claude Code、Codex……）远程访问。

graph TB
    A[junos-mcp<br/>remote server] <-- "OAuth 2.1 + HTTPS" --> B[mcp-stdio<br/>proxy]
    B <-- "STDIO" --> C[MCP client<br/>Claude / Codex / …]

步骤 1：在远程服务上以 Streamable HTTP 模式启动 junos-mcp

JUNOS_OPS_CONFIG=~/.config/junos-ops/config.ini \
  python -m junos_mcp --transport streamable-http

服务默认监听 http://localhost:8000/mcp。

步骤 2：在本地机器上将 mcp-stdio 注册为 MCP 服务

# Claude Code
claude mcp add junos-mcp -- mcp-stdio https://your-server:8000/mcp

# Codex
codex mcp add junos-mcp -- mcp-stdio https://your-server:8000/mcp

mcp-stdio 负责处理 OAuth 2.1 身份验证（RFC 8414 发现、RFC 7591 动态客户端注册、PKCE），并转发 STDIO ↔ Streamable HTTP。

有关详细配置（包括 OAuth 提供方设置），请参阅 mcp-stdio README。

当 junos-mcp 由 mcp-stdio serve（网关模式）启动且运行于 MCP SDK 2.x 时，请使用 mcp-stdio 0.43.7 或更高版本。较旧的网关会转发 2.x 服务无法接受的请求信封；使用这些网关时，请安装 mcp<2。

MCP Inspector（开发）

mcp dev junos_mcp/server.py

测试

pytest tests/ -v

133 项测试涵盖全部 23 个工具、连接池、辅助函数和边缘情况。

线上冒烟测试

这些测试会模拟 PyEZ，因此运行速度很快——但也因此无法发现某个工具是否已停止返回真实数据。 scripts/smoke_test.py 会使用已配置的设备测试每个已注册工具，并在返回空内容、格式错误或错误结果时失败：

# uses the same inventory file as the server (JUNOS_OPS_CONFIG)
uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only facts --traceback

• 只读。 按名称跳过 push_config、push_config_start、copy_package、install_package、 rollback_package 和 schedule_reboot，并通过测试确保这一点。collect_rsi / collect_rsi_batch 也会跳过——它们不会更改任何内容，但会占用 RE CPU 数分钟，并为每台设备生成一个文件，而没有任何断言会读取这些文件。命令运行工具会使用 show system uptime 进行测试：它们通常接受操作命令，而冒烟测试绝不应成为输入重要命令的那一方。
• 报告中不包含有效载荷。 仅显示工具名称和状态；错误文本也会经过脱敏，因为这些工具会引用被查询的设备，而有效载荷是配置内容。
• 规格中不包含特定设备群的信息。 每台主机工具所需的设备会在运行时从已配置的设备清单中发现，而 get_package_info 所需的硬件型号则来自该设备自身的事实信息。两项测试确保这一点：一项禁止将这些参数写成字面值，另一项禁止文件中出现任何类似地址的内容，因为此仓库是公开的。
• 每项探测都会拒绝这些工具以错误文本形式返回、而非抛出异常的 Error: ... / Connection error: ... 行——否则无法连接的设备也会被视为调用成功。
• CI 会检查较易实现的部分：注册了工具却没有探测规格时，构建会失败（tests/test_smoke_probes.py），因此添加工具时必须考虑“我们如何确认它能正常工作？”。
• scripts/smoke_harness.py 是执行引擎，不包含任何 JUNOS 知识：它在共用此引擎的各服务之间保持一致，因此修复引擎错误时只需修复一次，并同步该文件，而不是只修改此副本。

架构

从设计上确保标准输出安全

从 junos-ops 0.14.1 开始，核心函数会返回结构化的 dict 值，且不会向标准输出打印内容；MCP 工具通过 junos_ops.display.format_*() 格式化输出。无需使用 contextlib.redirect_stdout，因此 MCP STDIO JSON-RPC 通道能保持干净。

全局状态初始化

junos-ops 将 common.args 和 common.config 用作全局变量。MCP 服务按照 junos-ops 中测试固件（conftest.py）采用的相同模式初始化这些变量。

并行执行

批处理工具（run_show_command_batch、collect_rsi_batch）通过 junos-ops 的 common.run_parallel() 使用 ThreadPoolExecutor，并支持配置 max_workers。

许可证

Apache License 2.0