mcp-oxidized

MCP server exposing Oxidized network configuration backups to AI assistants with actionable error messages.

mcp-oxidized is a Model Context Protocol (MCP) server that connects AI assistants (Claude Desktop, Cursor, Zed, Windsurf) to your Oxidized network device configuration backup system.

Key Differentiator: When something goes wrong, you get structured error messages that LLMs can understand and act upon - not cryptic stack traces.

Quick Start

Get up and running in less than 5 minutes:

1. Prerequisites

• Oxidized 0.35.0+ with oxidized-web 0.18.0+ running and accessible
• An MCP-compatible client (Claude Desktop, Cursor, Zed, Windsurf)

Note: The REST API is provided by oxidized-web, a separate Ruby gem from Oxidized itself.

2. Installation

Option A: Download binary (recommended)

Download the latest binary for your platform from Releases.

Option B: Build from source

cargo install mcp-oxidized
# or
git clone https://github.com/fxthiry/mcp-oxidized.git
cd mcp-oxidized
cargo build --release

3. Configuration

Add to your MCP client config. Example for Claude Desktop (~/.config/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "oxidized": {
      "command": "/path/to/mcp-oxidized",
      "env": {
        "OXIDIZED_URL": "https://your-oxidized-server:8888",
        "OXIDIZED_USER": "admin",
        "OXIDIZED_PASSWORD": "your-password"
      }
    }
  }
}

Zero-config mode: If no env vars are set, defaults to http://localhost:8888 with no authentication.

📖 Full Configuration Guide - All environment variables, MCP client configs (Cursor, Zed, Windsurf), SSL options, custom headers, and security best practices.

Tools

Tool	Parameters	Description
fetch_node_config	node	Trigger immediate backup of a node's configuration
prioritize_node	node	Move a node to the front of the backup queue
reload_sources	(none)	Reload Oxidized source inventory (new devices become available)
diff_configs	node, version1, version2	Compare two configuration versions using Myers/LCS algorithm
search_configs	pattern, nodes?, case_sensitive?, limit?	Search regex patterns across all device configurations

Resources

Resource URI	Description
oxidized://nodes	List all nodes with pagination (offset, limit, group)
oxidized://node/{name}	Node details (model, status, last backup time)
oxidized://node/{name}/config	Current configuration (with truncate, summary options for large configs)
oxidized://node/{name}/versions	Configuration version history
oxidized://node/{name}/versions/{oid}	Specific historical version content
oxidized://stats	Global backup statistics

Actionable Errors

When something goes wrong, mcp-oxidized provides structured error messages optimized for AI assistants:

[Error] Node 'SW-Unknown' not found.
[Context] Search performed in Oxidized inventory.
[Suggestions] Similar nodes: SW-Core-01, SW-Access-02.
[Next Step] Use 'oxidized://nodes' to list all available nodes.

This format helps LLMs understand what went wrong and suggest corrections automatically.

Example Usage

Ask your AI assistant:

• "List all network devices in Oxidized"
• "Show me the configuration of router-core-01"
• "Compare the last two versions of switch-access-02"
• "Find all devices with SNMP community 'public' configured"
• "Trigger a backup of firewall-edge-01 now"

---

Security Considerations

⚠️ Important: Network device configurations often contain sensitive information (passwords, SNMP communities, VPN keys, ACLs, etc.). By using mcp-oxidized, you are giving your AI assistant access to this data.

Recommendations:

• Review what you share - Be mindful when asking your AI to analyze configurations; the content is sent to the LLM provider
• Use with trusted LLM providers - Ensure your organization's policies allow sending network configuration data to the AI service you're using
• Consider data residency - Some LLM providers may process data in different jurisdictions
• Limit scope when possible - Use node filtering in searches rather than querying all configurations

mcp-oxidized itself does not log or transmit configuration content beyond what the MCP protocol requires for your AI assistant to function.

---

Contributing

Contributions are welcome! See CONTRIBUTING.md for development setup, testing, and PR guidelines.

Documentation

• Tools Reference - Detailed tool documentation with examples
• Resources Reference - Resource URI patterns and response formats
• Configuration Guide - All environment variables and options
• Troubleshooting - Common errors and solutions

License

Apache License 2.0 - see LICENSE for details.