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

Resources

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.