eos-mcp

English | 日本語

MCP server for Arista EOS device operations via eAPI.

Exposes EOS show commands, running-config retrieval, configuration push (via configure session with commit timer), and tech-support collection to MCP-compatible AI assistants.

Documentation: https://shigechika.github.io/eos-mcp/

Installation

pip install eos-mcp

Configuration

Copy config.ini.example to ~/.config/eos-mcp/config.ini and fill in credentials:

[DEFAULT]
username = admin
password = yourpassword
transport = https
verify = false

[switch1.example.com]
tags = main,dc1

[switch2.example.com]
tags = main,dc1

Config file discovery order:

1. EOS_MCP_CONFIG environment variable
2. ./config.ini (current directory)
3. ~/.config/eos-mcp/config.ini

(Individual MCP tool calls may also override the path via a config_path parameter.)

Write operations

Three tools change device state through a guarded path:

Give the config.ini account for a device a lower-privilege, show-only role and these three tools fail against the EOS API instead of writing; every read-only tool for that device keeps working.

run_command, run_commands, run_command_batch, and run_commands_batch are not restricted to show ... commands, despite being documented and grouped as command runners. Nothing in the server validates or whitelists the command text — it is passed to the eAPI Command API verbatim — so these tools can execute arbitrary enable-mode EOS commands, including configure terminal ... or reload, on any configured device (a single host, or fleet-wide via tags in the _batch variants). This is gated by the same EOS account privilege as push_config, but without push_config's dry_run / commit-timer safety net — a de facto second write path worth remembering when deciding how privileged a device's config.ini account should be.

Usage

Claude Code (plugin)

This repository doubles as a single-plugin marketplace, so Claude Code can install the server for you:

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

The plugin launches uvx eos-mcp and reads EOS_MCP_CONFIG, the same variable described in Configuration. Leave it unset and the server falls through to its normal discovery order (./config.ini, then ~/.config/eos-mcp/config.ini). /plugin install only wires up the server process — it cannot create the config.ini file or the per-device eAPI credentials it holds; that file must already exist on the machine running the plugin before any tool but health_check will succeed.

uvx must be on the PATH of the process that runs Claude Code — a login shell usually has it, but a GUI-launched app may not; install uv system-wide if the plugin fails to start.

Claude Code (manual)

In .mcp.json:

{
  "mcpServers": {
    "eos-mcp": {
      "type": "stdio",
      "command": "eos-mcp"
    }
  }
}

Add "env": { "EOS_MCP_CONFIG": "..." } only if config.ini is not at one of the default discovery locations above.

Claude Desktop

Add the same entry to claude_desktop_config.json.

From a shell

# Verify config and list devices
eos-mcp --check

# Test connectivity to a specific host
eos-mcp --check --check-host switch1.example.com

# Start MCP server (stdio transport)
eos-mcp

Tools

Development

Live smoke test

Unit tests check logic against fixtures; they cannot tell you that a tool has stopped returning real data. scripts/smoke_test.py runs every registered tool against the configured devices and fails on empty, malformed or error answers:

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

• Read-only. push_config, confirm_config_session and abort_config_session are skipped by name, and a test enforces that. collect_tech_support is skipped too — it changes nothing, but it is minutes of device CPU for an answer no assertion would read. The command-running tools are exercised with show version: they accept enable-mode commands in general, and a smoke test must not be the thing that types one that matters.
• No payloads in the report. Tool names and statuses only; error text is redacted too, since every error here is prefixed with the device it came from and the payloads are configuration.
• Nothing estate-specific in the specs. The device the per-host tools need is discovered at run time from the configured inventory, and skipped when it is empty. Two tests keep it that way: one refuses those parameters as literals, the other bans anything address-shaped anywhere in the file, because this repository is public.
• Every probe refuses the Error (<host>): ... line these tools return in place of raising — otherwise an unreachable device would read as a successful call.
• CI enforces the cheap half: a tool registered without a probe spec fails the build (tests/test_smoke_probes.py), so adding a tool forces the question "how would we know it works?".
• scripts/smoke_harness.py is the engine and holds no EOS knowledge: it is kept identical across the servers that share it, so fix engine bugs once and sync the file rather than patching this copy.

Requirements

• Python >= 3.10
• Arista EOS with eAPI enabled (management api http-commands)
• Network access to port 443 (HTTPS) on target devices

License

Apache-2.0