Junos MCP

junos-mcp

English | 日本語

MCP (Model Context Protocol) server for junos-ops.

Exposes Juniper Networks device operations to MCP-compatible AI assistants (Claude Desktop, Claude Code, OpenAI Codex, etc.) via STDIO transport. While junos-ops is the CLI tool for humans, junos-mcp is the AI-facing interface to the same powerful engine.

Features

Device Information

CLI Command Execution

Configuration Management

Upgrade Operations

Diagnostics

Pre-flight Checks

Equivalent to the junos-ops check subcommand modes. All three reuse the junos-ops display layer for table rendering.

Daily Operations

Safety by Design

All destructive operations (push_config, copy_package, install_package, rollback_package, schedule_reboot) default to dry-run mode (dry_run=True). The AI assistant must explicitly set dry_run=False to make changes.

push_config provides additional safety features not found in other Junos MCP servers:

• commit confirmed with configurable timeout (auto-rollback if not confirmed)
• Fallback health check after commit (ping, NETCONF uptime probe, or any CLI command)
• Automatic rollback if health check fails (commit is not confirmed, timer expires)
• `no_commit=True` — issues commit confirmed but intentionally skips the final commit. JUNOS auto-rolls back after confirm_timeout minutes. Useful for restarting services that lack a request ...restart command (e.g. syslog daemon on EX3400 post-upgrade).

RPC timeout and the per-call deadline. Every load/commit RPC uses timeout from the host's config.ini section, else the junos-ops model default: 180 s on SRX branch models (SRX300/320/340/345 and the like, whose commits can exceed 30 s), 120 s otherwise. It is never shortened. With JUNOS_DEADLINE set (default 45 s; 0 disables), push_config runs the push as a background job and waits for it until shortly before the deadline: if it finishes, the answer is the same as without a deadline; if not, the answer says Still running with a job_id to poll with push_config_result. push_config_start returns the diff and the job_id without waiting for the commit; the job loads and diffs the change and then commits on the same locked session, so what is committed is exactly the diff returned. A failure after commit confirmed has been sent is reported as a possibly pending commit that rolls back on the device after confirm_timeout minutes. Only one push per host runs at a time; a second one is refused, and other tools on that host wait at most until the deadline and then answer host busy.

Requirements

• Python 3.12+
• junos-ops with a valid config.ini
• MCP Python SDK >= 1.0

Installation

pip install junos-mcp

Or for development:

git clone https://github.com/shigechika/junos-mcp.git

cd junos-mcp python3 -m venv .venv . .venv/bin/activate pip install -e ".[test]"

CLI options

python -m junos_mcp --help

--check is handy to verify JUNOS_OPS_CONFIG and config.ini are reachable before registering the server with an AI assistant. Combine with --check-host rt1 to also confirm that credentials actually authenticate against a real device.

Tag-based host filtering

run_show_command_batch, collect_rsi_batch, and get_router_list accept an optional tags argument. The grammar matches the junos-ops --tags CLI flag (since junos-mcp 0.9.0 / junos-ops 0.16.6):

• Each list element is one tag group. Comma-separated tags inside a group AND together.
• Multiple list elements OR together across groups.
• When combined with hostnames on batch tools, the result is the intersection (tags filter further narrowed by names). An empty intersection returns an error.

# 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"], )

See the junos-ops tag documentation for how to tag sections in config.ini and for the matching CLI grammar.

Structured output format

run_show_command and run_show_commands accept an optional output_format parameter:

Note: CLI pipe stages (| match, | last, | count, etc.) are silently dropped regardless of output_format. PyEZ's Device.cli() sends the command over NETCONF RPC, which JunOS does not pipe-process. Run the command without pipes and filter client-side instead. For a single command, run_show_command_batch's grep_pattern argument (see below) offers server-side-style filtering — even against a single host, by passing a one-element hostnames list — but it always fetches plain-text output internally (it cannot be combined with output_format="json"/"xml"), and it only accepts one command at a time, so it isn't a drop-in workaround for run_show_commands' multi-command case.

# Get structured BGP summary data

run_show_command("router-a", "show bgp summary", output_format="json")

Server-side output filtering

run_show_command_batch accepts an optional grep_pattern argument (Python re pattern). When set, only lines matching the pattern are kept from each host's output. Header lines (starting with #) are always preserved. Hosts with no matching lines show (no match).

This reduces large batch results — for example, 93 routers × show route summary — from hundreds of KB to a few hundred bytes by extracting just the relevant lines:

# 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", )

Connection pool

junos-mcp maintains a per-host NETCONF connection pool. Reusing an idle Device avoids the TCP/NETCONF handshake on every tool call; the pool serialises concurrent operations on the same host through a per-host lock.

Security note: pooled connections are long-lived SSH sessions. In environments where session duration is restricted by policy, set JUNOS_MCP_POOL_IDLE to a value shorter than the inactivity limit, or set JUNOS_MCP_POOL=0 to disable the pool entirely.

Configuration