mcp-oxidized
The mcp-oxidized server integrates with Oxidized to provide network device configuration management via MCP, allowing you to query, compare, analyze, and retrieve configurations. Key capabilities include:
List all devices: Retrieve all managed devices with details like name, model, group, IP, last backup time, and status.
Find devices: Search by partial/full name or IP (case-insensitive).
Get device status: Backup status and last run for a specified device.
Get device versions: List historical configuration versions with timestamps.
Prepare & retrieve configurations: Stage current configs with
prepare_config, then fetch viaoxidized://config/get_content(prepare-then-read pattern for large outputs).Prepare & retrieve blame: Stage and retrieve annotated configuration blame with
prepare_blameandoxidized://config/get_blame.Inline diff:
get_config_with_inline_diffdisplays current config with inline change markers against a historical version.Unified diff:
get_diff_between_versionsgenerates a diff between any two historical versions with configurable context.
Key behaviors: case-insensitive device matching, bearer token authentication linking prepare and read calls, live data fetching from Oxidized with no caching.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-oxidized List all devices and show which failed their last backup."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-oxidized
MCP server for Oxidized, a network device configuration backup tool.
It exposes Oxidized data as MCP tools and resources, allowing assistants to query, compare, analyze, and retrieve network device configurations.
Features
Capability | Description |
| List all devices managed by Oxidized |
| Find devices by exact or partial name, full name, or IP address |
| Show backup status and last run details for a device |
| List stored configuration versions for a device |
| Select one or more devices for the current-config resource |
| Retrieve all current configurations selected by |
| Select a device for the static blame resource |
| Retrieve the configuration blame prepared by |
| Show current config with inline change markers against a version |
| Unified diff between two historical versions with configurable context |
All device-specific tools accept an exact device name or a unique partial name. Matching is case-insensitive. If a partial name matches multiple devices, the server returns candidates and asks for a more specific name or group.
Related MCP server: Cisco Meraki MCP Server
Prepared configuration resources
Current configurations can be too large for a tool response. Use prepare_configs
to resolve one or more devices, then read the static multi-content resource. The
prepare tool returns device metadata only and does not load configuration data.
prepare_configs(nodes=["router01"], group="Core")
read oxidized://config/get_contents
prepare_configs(nodes=["router01", "switch02"], group="Core")
read oxidized://config/get_contentsThe resource returns a separate content item for every prepared device. Each item
has a unique oxidized://config/<group>/<node> URI and uses this MIME type:
text/plain; charset=utf-8The client must send the same Bearer token with both the prepare call and the later resource read:
Authorization: Bearer <long-random-token>The server hashes this token and uses the hash only as an in-memory lookup key. The original token is not stored or logged, and it is not validated as an identity credential. This allows selections to survive a client opening different MCP transport sessions for tool calls and resource reads.
Current configuration and blame selections are separate, so both resources can refer to different devices for the same Bearer token. Resource reads fetch the current configuration and required historical versions live from Oxidized. No configuration, version, or blame result is cached or written to a database.
If a resource is read before its matching prepare tool, it returns instructions for the required prepare call. A server restart clears all prepared selections. Run one server worker because prepared selections are intentionally held only in that process memory.
Requirements
Python 3.11+
Oxidized with oxidized-web running and its REST API enabled
Docker, recommended
Quick start
cp .env.example .env
# Edit .env with your Oxidized URL and credentials
docker compose up -dThe MCP server listens on port 8000 using Streamable HTTP transport.
Configuration
Variable | Description | Default |
| Base URL of the Oxidized instance | required |
| Basic Auth username | required |
| Basic Auth password | required |
| MCP server port | 8000 |
MCP client configuration
Configure the client to send a stable Bearer token on every MCP request:
Authorization: Bearer <long-random-token>The token associates prepare_configs and prepare_blame calls with later
resource reads. Treat it as a secret because a caller using the same token can
access and replace that token's prepared selections.
Example prompts
"List all devices and show which ones failed their last backup."
"Find the device containing
HFGBF253in its name.""Show the status of the device matching
253-IT.""List stored versions for
HFGBF253-ITin theFirewallsgroup.""Prepare the current configuration of router01."
"Prepare the current configurations of router01, switch02, and firewall03."
"Prepare configuration blame for switch02."
"Show the current config of switch02 and highlight changes against version 12."
"Show the diff between version 12 and version 14 for firewall01 with 10 lines of context."
Development
pip install -e ".[dev]"
python -m mcp_oxidized.serverLicense
MIT
Available Tools
8 toolsfind_devicesA
Find Oxidized devices by exact or partial name, full name, or IP address. Matching is case-insensitive. Use this before other device tools when only part of a device name is known.
Inputs: query (required), group. Returns: result
get_config_with_inline_diffA
Return the complete current configuration with inline change markers relative to a reference version number. The node may be an exact name or a unique partial name.
Inputs: node (required), ref_version (required), group, context_lines. Returns: result
get_device_statusA
Return status details for a single device. The node may be an exact name or a unique partial name.
Inputs: node (required), group. Returns: result
get_device_versionsA
Return all available configuration versions for a device. The node may be an exact name or a unique partial name. Versions are numbered oldest-first: version 1 is the oldest and the highest number is the newest. Each entry includes its timestamp and OID.
Inputs: node (required), group. Returns: result
get_diff_between_versionsA
Return a unified diff between two historical versions of a device configuration. The node may be an exact name or a unique partial name.
Inputs: node (required), version_a (required), version_b (required), group, +1 more. Returns: result
list_devicesA
Return all devices managed by Oxidized. Each entry includes: name, model, group, ip, last backup time, status.
Inputs: no named parameters. Returns: result
prepare_blameA
Prepare one device's configuration blame for the static get_blame resource. The node may be an exact name or a unique partial name. This tool returns only device metadata; read oxidized://config/get_blame for the annotated config.
Inputs: node (required), group. Returns: result
prepare_configA
Prepare one device's current configuration for the static get_content resource. The node may be an exact name or a unique partial name. This tool returns only device metadata; read oxidized://config/get_content for the configuration.
Inputs: node (required), group. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Tools are mostly distinct: list/find/status cover device discovery and health, while version/config/diff tools focus on configuration history. Some overlap exists between get_device_versions, get_config_with_inline_diff, and get_diff_between_versions, but descriptions clarify their specific purposes.
All tool names follow a consistent verb_noun pattern in lowercase snake_case (list_devices, find_devices, get_device_status, prepare_config, etc.). The pattern is predictable and uniform across the set.
8 tools is well within the ideal range for a network device configuration management server. Each tool addresses a distinct aspect of device listing, status, versioning, and configuration diffing without unnecessary redundancy.
Core operations are covered: device discovery, status, version listing, current config, and diffs. However, there is no direct way to retrieve a full historical config version (as opposed to a diff), which is a notable gap for a configuration backup tool.
Maintenance
Related MCP Connectors
Read-only MCP access to a documented IT fleet: state, changes, posture. 15 tools.
Manage CloudPepper servers, Odoo instances, backups, and deployments over MCP.
Manage Pipefork API projects, drafts, connections, secrets, and deployments through MCP.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseAqualityBmaintenanceProvides MCP tools for governed multi-vendor network device operations, including configuration management (backup, diff, merge, replace, rollback) and read-only queries (facts, interfaces, BGP, LLDP, ARP) via NAPALM, with optional NetBox source-of-truth integration.33MIT
- FlicenseNot gradedqualityDmaintenanceProvides MCP tools for Cisco Meraki Dashboard API, enabling management of networks, configuration templates, and health checks via natural language commands.-
- FlicenseNot gradedqualityDmaintenanceEnables read-only access to managed network devices over SSH or Telnet via MCP, allowing users to probe devices, retrieve redacted running or startup configs, gather facts and interfaces, back up multiple devices, and compare configs for drift or unsaved changes.-
- AlicenseAqualityBmaintenanceEnables AI assistants to interact with Oxidized network device backups through MCP, including listing and filtering devices, checking backup health, reading and regex-searching configs, browsing git version history and diffs, and triggering backups with read-only and credential-redaction options.1156 PyPI1MIT