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

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: mcp-server-sros

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_contents

The 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-8

The 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 -d

The MCP server listens on port 8000 using Streamable HTTP transport.

Configuration

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 HFGBF253 in its name."

• "Show the status of the device matching 253-IT."

• "List stored versions for HFGBF253-IT in the Firewalls group."

• "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.server

License

MIT