Oxidized MCP

Oxidized MCP Server

Let AI agents search, compare and back up network device configs stored in Oxidized

Installation · Tools · Configuration · Security

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 to 3.15
• 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).

A query string (?...) is rejected; use the Basic auth settings below, or

percent-encode special characters in credentials put in the URL.

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

Redact node vars (often device credentials) in tool output

OXIDIZED_REDACT_NODE_VARS=true

Read-Only Mode

Set READ_ONLY_MODE true to disable operations (trigger_node_backup, reload_nodes)

READ_ONLY_MODE=false

Disabled Tags

Comma-separated list of tags to disable tools for (empty by default)

Example: OXIDIZED_DISABLED_TAGS=search,diff

OXIDIZED_DISABLED_TAGS=

Logging Configuration

LOG_LEVEL=INFO

Rate Limiting (requests per minute)

Set RATE_LIMIT_ENABLED true to enable rate limiting

RATE_LIMIT_ENABLED=false RATE_LIMIT_MAX_REQUESTS=60 RATE_LIMIT_WINDOW_MINUTES=1

Tool Search Transform (Optional)

Set TOOL_SEARCH_ENABLED true to replace full tool listings with search_tools + call_tool

TOOL_SEARCH_ENABLED=false

Search strategy: bm25 (natural language) or regex (pattern match)

TOOL_SEARCH_STRATEGY=bm25

Maximum number of tools returned by search_tools

TOOL_SEARCH_MAX_RESULTS=5

Sentry Error Tracking (Optional)

Set SENTRY_DSN to enable error tracking and performance monitoring

SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789

Optional Sentry configuration

SENTRY_TRACES_SAMPLE_RATE=1.0

SENTRY_SEND_DEFAULT_PII=false

SENTRY_ENVIRONMENT=production

SENTRY_RELEASE=1.2.3

SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

SENTRY_PROFILE_LIFECYCLE=trace

SENTRY_ENABLE_LOGS=true

MCP Transport Configuration

Transport type: 'stdio' (default), 'sse' (Server-Sent Events), or 'http' (HTTP Streamable)

'streamable-http' is accepted as an alias for 'http'. Any other value stops

the server at startup.

MCP_TRANSPORT=stdio

HTTP Transport Settings (used when MCP_TRANSPORT=sse or MCP_TRANSPORT=http)

Host to bind the HTTP server (default: 127.0.0.1)

MCP_HTTP_HOST=127.0.0.1

Port to bind the HTTP server (default: 8000)

MCP_HTTP_PORT=8000

Optional bearer token for authentication (leave empty for no auth)

MCP_HTTP_BEARER_TOKEN=

Sentry Error Tracking & Monitoring (Optional)

The server optionally supports Sentry for error tracking, performance monitoring, and debugging. Sentry integration is completely optional and only initialized if configured.

Installation

To enable Sentry monitoring, install the optional dependency:

# Using UV (recommended)

uv sync --extra sentry

Configuration

Enable Sentry by setting the SENTRY_DSN environment variable in your .env file:

# Required: Sentry DSN for your project

SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789

Optional: Performance monitoring sample rate (0.0-1.0, default: 1.0)

SENTRY_TRACES_SAMPLE_RATE=1.0

Optional: Include personally identifiable information (default: false).

Keep it off: with the MCP integration it records tool results, which are

full device configurations including secrets.

SENTRY_SEND_DEFAULT_PII=false

Optional: Environment name (e.g., "production", "staging")

SENTRY_ENVIRONMENT=production

Optional: Release version (auto-detected from package if not set)

SENTRY_RELEASE=1.2.2

Optional: Profiling - continuous profiling sample rate (0.0-1.0, default: 1.0)

SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

Optional: Profiling - lifecycle mode for profiling (default: "trace")

Options: "all", "continuation", "trace"

SENTRY_PROFILE_LIFECYCLE=trace

Optional: Enable log capture as breadcrumbs and events (default: true)

SENTRY_ENABLE_LOGS=true

Features

When enabled, Sentry automatically captures:

• Exceptions & Errors: All unhandled exceptions with full context
• Performance Metrics: Request/response times and traces
• MCP Integration: Detailed MCP server activity and interactions
• Logs & Breadcrumbs: Application logs and event trails for debugging
• Context Data: Environment, client info, and request parameters

Getting a Sentry DSN

1. Create a free account at sentry.io
2. Create a new Python project
3. Copy your DSN from the project settings
4. Set it in your .env file

Disabling Sentry

Sentry is completely optional. If you don't set SENTRY_DSN, the server will run normally without any Sentry integration, and no monitoring data will be collected.

🧰 Available Tools

Node Tools

• list_nodes: List devices with optional filters (group, model, last run status, name/IP substring) and paging; group/model are filtered by Oxidized itself (/nodes/ / .json), so large inventories are not transferred in full
• get_node: Get a single device's details and last backup run (accepts name or IP)
• find_nodes: Find devices by partial name, full name or IP, exact matches first
• get_backup_stats: Backup health summary - counts per status, group and model, success rate, failed / never backed up / stale devices; optionally for a single group or model

Configuration Tools

• get_node_config: Get the latest backed-up configuration of a device (by name or IP), paged by lines (offset / max_lines)
• search_configs: Search all configurations for a regex or literal text; returns matching lines with line numbers and optional context

Version History Tools

Require the Oxidized git or gitcrypt output.

• list_node_versions: List stored configuration versions (oid, date, author, message), newest first
• get_node_version: Get the configuration at a given version (full oid or unique prefix), paged by lines
• diff_node_versions: Unified diff between two versions; defaults to the most recent change

Operation Tools

Hidden when READ_ONLY_MODE=true.

• trigger_node_backup: Queue an immediate backup of a device, optionally recording a commit message and author
• reload_nodes: Reload the whole node list from its source (a per-node reload is deliberately not offered: oxidized-web's /reload?node=X replaces the entire in-memory node list with the matching nodes)

🔒 Security & Safety Features

Read-Only Mode

The server supports a read-only mode that disables all write operations for safe monitoring:

READ_ONLY_MODE=true

When enabled, only tools tagged read-only are exposed: trigger_node_backup and reload_nodes are hidden, while every node, configuration and history tool stays available.

Tag-Based Tool Filtering

You can disable specific categories of tools by setting disabled tags:

OXIDIZED_DISABLED_TAGS=search,diff

Available tags include:

• node - Node listing and lookup tools