Oxidized MCP server

Oxidized MCP Server

<!-- mcp-name: io.github.mhajder/oxidized-mcp -->

Oxidized MCP Server is a Python-based Model Context Protocol (MCP) server that gives AI assistants access to Oxidized, the network device configuration backup tool. It talks to the oxidized-web REST API to list devices, check backup health, read and search device configurations, browse and diff configuration history, and queue backups. It supports read-only mode, tag-based tool filtering, and bearer token authentication for HTTP transports.

Features

Core Features

• List and filter managed devices by group, model and last backup status
• Find devices by partial name, full name (group/name) or IP address
• Summarise backup health: failures, devices never backed up and stale backups
• Read the latest backed-up configuration of any device, paged for large configs
• Search all configurations for a regular expression or literal text, with matching lines and context

Configuration History

• List the stored configuration versions of a device (git output)
• Read a device's configuration as it was at any version (full oid or short prefix)
• Diff two versions, or just see the most recent change, as a unified diff

Operations

• Queue an immediate backup of a device, optionally with a commit message and author
• Reload the node list from its source (router.db, SQL, HTTP, ...)
• Read-only mode hides every operation for safe monitoring

Advanced Capabilities

• Node vars (often device credentials) are redacted in tool output by default
• HTTP Basic auth for oxidized-web behind a reverse proxy
• Rate limiting, SSL/TLS verification and configurable timeouts
• Tag-based tool filtering and an optional tool-search transform
• Bearer token authentication for HTTP transports

Installation

Prerequisites

• Python 3.11 or higher
• A running Oxidized instance with oxidized-web enabled
• For version history and diffs: the Oxidized git (or gitcrypt) output

Quick Install from PyPI

The easiest way to get started is to install from PyPI:

# Using UV (recommended)
uvx oxidized-mcp

# Or using pip
pip install oxidized-mcp

Remember to configure the environment variables for your Oxidized instance before running the server:

# Create environment configuration
export OXIDIZED_URL=http://localhost:8888

For more details, visit: https://pypi.org/project/oxidized-mcp/

Install from Source

1. Clone the repository:

git clone https://github.com/mhajder/oxidized-mcp.git
cd oxidized-mcp

1. Install dependencies:

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

1. Configure environment variables:

cp .env.example .env
# Edit .env with your Oxidized URL (and Basic auth credentials if needed)

1. Run the server:

# Using UV (recommended)
uv run oxidized-mcp

# Or using the installed command directly
oxidized-mcp

Development Setup

For development with additional tools:

# Clone and install with development dependencies
git clone https://github.com/mhajder/oxidized-mcp.git
cd oxidized-mcp
uv sync --group dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov=src/

# Run linting and formatting
uv run ruff check .
uv run ruff format .

# Run type checking
uv run ty check .

# Setup prek hooks
uv run prek install

Configuration

Environment Variables

# Oxidized Connection Details
# Base URL of oxidized-web (include the url_prefix if one is configured)
OXIDIZED_URL=http://localhost:8888

# Optional HTTP Basic auth, e.g. for a reverse proxy in front of oxidized-web
# OXIDIZED_USERNAME=
# OXIDIZED_PASSWORD=

# SSL Configuration
OXIDIZED_VERIFY_SSL=true
OXIDIZED_TIMEOUT=30
# Timeout for search_configs (oxidized-web reads every configuration)
OXIDIZED_SEARCH_TIMEOUT=300

Shortened. The full README is on GitHub.