Oxidized MCP

Oxidized MCP Server は、ネットワーク機器の設定バックアップツールである Oxidized に AI アシスタントがアクセスできるようにする、Python ベースの Model Context Protocol（MCP）サーバーです。oxidized-web REST API と通信し、機器の一覧表示、バックアップの健全性チェック、機器設定の読み取りと検索、設定履歴の閲覧と差分比較、バックアップのキュー登録を行います。読み取り専用モード、タグベースのツールフィルタリング、HTTP トランスポート向けのベアラートークン認証に対応しています。

✨ 機能

コア機能

• 管理対象の機器を一覧表示し、グループ、モデル、最終バックアップの状態で絞り込めます
• 部分的な名前、完全な名前（group/name）、IP アドレスで機器を検索できます
• バックアップの健全性を要約します：失敗、バックアップが一度も行われていない機器、古いバックアップ
• 大規模な設定はページ分割して、任意の機器の最新バックアップ設定を読み取れます
• すべての設定を正規表現またはリテラルテキストで検索し、一致した行とその前後のコンテキストを表示します

設定履歴

• 機器の保存済み設定バージョンを一覧表示します（git の出力）
• 任意のバージョン（完全な oid または短いプレフィックス）時点の機器設定を読み取れます
• 2 つのバージョン間の差分、または直近の変更のみを統一形式の差分で表示します

運用

• 任意でコミットメッセージと作成者を指定して、機器の即時バックアップをキューに登録します
• ソース（router.db、SQL、HTTP、...）からノード一覧を再読み込みします
• 読み取り専用モードでは、安全な監視のためにすべての操作が非表示になります

高度な機能

• ノード変数（多くの場合、機器の認証情報）は、デフォルトでツールの出力から秘匿されます
• リバースプロキシの背後にある oxidized-web 向けの HTTP Basic 認証
• レート制限、SSL/TLS 検証、設定可能なタイムアウト
• タグベースのツールフィルタリングと、オプションのツール検索トランスフォーム
• HTTP トランスポート向けのベアラートークン認証

🚀 インストール

前提条件

• Python 3.11〜3.15
• oxidized-web を有効にした、稼働中の Oxidized インスタンス
• バージョン履歴と差分表示には、Oxidized の git（または gitcrypt）出力

PyPI からのクイックインストール

最も簡単に始めるには、PyPI からインストールします：

# Using UV (recommended)
uvx oxidized-mcp

# Or using pip
pip install oxidized-mcp

サーバーを実行する前に、Oxidized インスタンス用の環境変数を設定してください：

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

詳しくは、https://pypi.org/project/oxidized-mcp/ をご覧ください。

ソースからのインストール

1. リポジトリをクローンします：

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

2. 依存関係をインストールします：

# Using UV (recommended)
uv sync

# Or using pip
pip install -e .

3. 環境変数を設定します：

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

4. サーバーを実行します：

# Using UV (recommended)
uv run oxidized-mcp

# Or using the installed command directly
oxidized-mcp

開発環境のセットアップ

追加ツールを使用した開発の場合：

# 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

🔧 設定

環境変数

# 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://[email protected]/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 によるエラー追跡とモニタリング（任意）

このサーバーは、エラー追跡、パフォーマンスのモニタリング、デバッグに Sentry を任意でサポートしています。Sentry との統合は完全に任意で、設定されている場合にのみ初期化されます。

インストール

Sentry のモニタリングを有効にするには、任意の依存関係をインストールします。

# Using UV (recommended)
uv sync --extra sentry

設定

.env ファイルで SENTRY_DSN 環境変数を設定して、Sentry を有効にします。

# Required: Sentry DSN for your project
SENTRY_DSN=https://[email protected]/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

機能

有効にすると、Sentry は次の情報を自動的に収集します。

• 例外とエラー：コンテキスト情報を含む、処理されなかったすべての例外
• パフォーマンス指標：リクエスト／レスポンス時間とトレース
• MCP との統合：MCP サーバーのアクティビティとインタラクションの詳細
• ログとブレッドクラム：デバッグ用のアプリケーションログとイベント履歴
• コンテキストデータ：環境、クライアント情報、リクエストパラメーター

Sentry DSN の取得

1. sentry.io で無料アカウントを作成します
2. 新しい Python プロジェクトを作成します
3. プロジェクト設定から DSN をコピーします
4. .env ファイルに設定します

Sentry の無効化

Sentry は完全に任意です。SENTRY_DSN を設定しない場合、サーバーは Sentry との統合なしで通常どおり動作し、モニタリングデータは収集されません。

🧰 利用可能なツール

ノードツール

• list_nodes：任意のフィルター（グループ、モデル、前回の実行ステータス、名前／IP の部分一致）とページ指定を使用してデバイスを一覧表示します。グループ／モデルの絞り込みは Oxidized 自体が行うため（/nodes/<group|model>/<value>.json）、大規模なインベントリー全体が転送されることはありません
• get_node：単一デバイスの詳細と最後のバックアップ実行結果を取得します（名前または IP を指定）
• find_nodes：部分一致の名前、完全一致の名前、または IP でデバイスを検索します。一致が完全なものを優先します
• get_backup_stats：ステータス、グループ、モデル別の件数、成功率、失敗したデバイス、バックアップが一度もないデバイス、古いデバイスを含む、バックアップの健全性の概要を取得します。単一のグループまたはモデルを指定することもできます

設定ツール

• get_node_config：デバイスの最新のバックアップ済み設定を取得します（名前または IP で指定）。行単位でページ指定できます（offset ／ max_lines）
• search_configs：すべての設定を正規表現またはリテラルテキストで検索し、一致する行と行番号、および任意の前後のコンテキストを返します

バージョン履歴ツール

Oxidized の git または gitcrypt 出力が必要です。

• list_node_versions：保存済みの設定バージョン（oid、日付、作成者、メッセージ）を新しい順に一覧表示します
• get_node_version：指定したバージョン（完全な oid または一意のプレフィックス）の設定を取得します。行単位でページ指定できます
• diff_node_versions：2 つのバージョン間の統一形式の差分を表示します。デフォルトでは直近の変更を対象とします

操作ツール

READ_ONLY_MODE=true の場合は非表示になります。

• trigger_node_backup：デバイスのバックアップを即時にキューに登録します。コミットメッセージと作成者を任意で記録できます
• reload_nodes：ノードリスト全体をソースから再読み込みします（ノード単位の再読み込みは意図的に提供していません。oxidized-web の /reload?node=X は、該当するノードでメモリ上のノードリスト全体を置き換えるためです）

🔒 セキュリティと安全機能

読み取り専用モード

安全なモニタリングのため、すべての書き込み操作を無効にする読み取り専用モードをサポートしています。

READ_ONLY_MODE=true

有効にすると、read-only タグが付いたツールのみが公開されます。trigger_node_backup と reload_nodes は非表示になり、ノード、設定、履歴に関するその他のツールはすべて引き続き利用できます。

タグベースのツールフィルタリング

無効にするタグを設定して、特定のカテゴリのツールを無効にできます。

OXIDIZED_DISABLED_TAGS=search,diff

利用可能なタグは次のとおりです。

• node - ノードの一覧表示および検索ツール（バックアップ／再読み込み操作を含む）
• stats - バックアップの健全性統計
• config - 設定の読み取りツール
• search - 設定の検索およびノードの検索ツール
• version - バージョン履歴ツール
• diff - バージョン差分ツール
• backup - バックアップの開始操作
• reload - ノードリストの再読み込み操作
• read-only - Oxidized の状態を変更しないすべてのツール

レート制限

サーバーは、API の使用量を制御し、不正使用を防ぐためのレート制限に対応しています。有効にすると、スライディングウィンドウアルゴリズムを使用して、クライアントごとにリクエスト数が制限されます。

.env ファイルで次の環境変数を設定して、レート制限を有効にします。

RATE_LIMIT_ENABLED=true
RATE_LIMIT_MAX_REQUESTS=60    # Maximum requests allowed per window
RATE_LIMIT_WINDOW_MINUTES=1   # Window size in minutes

RATE_LIMIT_ENABLED を true に設定すると、サーバーはレート制限ミドルウェアを適用します。環境に応じて RATE_LIMIT_MAX_REQUESTS と RATE_LIMIT_WINDOW_MINUTES を調整してください。レート制限が有効な場合、どちらも 1 以上である必要があります。無効な場合は読み込まれません。

大規模なツールセット向けのツール検索

FastMCP のツール検索を使うと、多数のツールを持つサーバーでプロンプトのサイズを削減できます。 有効にすると、list_tools は次の 2 つの合成ツールを返します。

• search_tools：一致するツールを検索し、完全なスキーマを返します
• call_tool：名前で検出した任意のツールを実行します

次の設定で有効にします。

TOOL_SEARCH_ENABLED=true
TOOL_SEARCH_STRATEGY=bm25      # bm25 or regex
TOOL_SEARCH_MAX_RESULTS=8      # optional, default is 5

bm25 は自然言語クエリに対応し、regex は決定的なマッチングのために正規表現の pattern 入力を使用します。 ツール検索を有効にした場合、TOOL_SEARCH_STRATEGY に他の値を指定するとサーバーは起動時に停止し、 TOOL_SEARCH_MAX_RESULTS は 1 以上である必要があります。

ツール検索では、既存の可視性制御（読み取り専用モードおよび無効化されたタグ）が適用されます。

SSL/TLS の設定

サーバーは SSL 証明書の検証とカスタムタイムアウト設定に対応しています。

OXIDIZED_VERIFY_SSL=true    # Enable SSL certificate verification
OXIDIZED_TIMEOUT=30         # Request timeout in seconds

上流認証

oxidized-web 自体には認証機能がなく、通常は HTTP Basic 認証を使用するリバースプロキシの背後で公開されます。すべてのリクエストに Basic 認証を付与するには、両方の変数を設定します。

OXIDIZED_USERNAME=oxidized
OXIDIZED_PASSWORD=your-password

ノード変数の編集

Oxidized のソース（router.db、SQL、HTTP）に含まれるノード変数には、デバイスごとの認証情報が含まれていることが多く、oxidized-web は /nodes.json からそれらを未編集のまま返します。オプトアウトしない限り、サーバーは各変数の値を <redacted> に置き換えます（キーは保持されます）。

OXIDIZED_REDACT_NODE_VARS=false

トランスポートの設定

サーバーは、さまざまなデプロイシナリオに対応する複数のトランスポートプロトコルをサポートしています。

STDIO トランスポート（デフォルト）

デフォルトのトランスポートでは、通信に標準入力／出力を使用します。標準入力／出力を介して通信するツールとのローカルでの利用や統合に最適です。

MCP_TRANSPORT=stdio

HTTP SSE トランスポート（サーバー送信イベント）

ネットワーク経由でデプロイする場合は、サーバー送信イベントを使用した HTTP を利用できます。これにより、MCP サーバーに HTTP 経由でアクセスし、リアルタイムストリーミングを行えます。

MCP_TRANSPORT=sse
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

ベアラートークンを使って SSE トランスポートを利用する場合、クライアントはリクエストにトークンを含める必要があります。

curl -H "Authorization: Bearer your-secret-token" http://localhost:8000/sse

HTTP Streamable トランスポート

HTTP Streamable トランスポートは、リクエスト／レスポンスのストリーミングに対応した HTTP ベースの通信を提供します。ウェブとの統合や HTTP エンドポイントを必要とするツールに最適です。

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1        # Localhost
MCP_HTTP_PORT=8000           # Port to listen on
MCP_HTTP_BEARER_TOKEN=your-secret-token  # Optional authentication token

ベアラートークンを使って Streamable トランスポートを利用する場合：

curl -H "Authorization: Bearer your-secret-token" \
     -H "Accept: application/json, text/event-stream" \
     -H "Content-Type: application/json" \
     -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
     http://localhost:8000/mcp

注：HTTP トランスポートでは、jsonrpc フィールドと id フィールドを含む適切な JSON-RPC 形式が必要です。一部の操作では、サーバーのセッション初期化も必要になる場合があります。

ヘルスエンドポイント

両方の HTTP トランスポート（sse および http）は GET /health を提供します。このエンドポイントは、 サーバーがリクエストを処理している場合に 200 ok を返します。 ベアラートークンは不要で、Oxidized への接続も行わないため、Oxidized が停止しても MCP サーバーは正常と判定されます。 Docker イメージの HEALTHCHECK はこのエンドポイントを使用します。

curl http://localhost:8000/health

📝 Oxidized の注意事項

• バージョン履歴（list_node_versions、get_node_version、diff_node_versions）には、git または gitcrypt の出力が必要です。file 出力の場合、Oxidized はバージョンがないと報告します。
• グループ：ノード名は一意にしてください。ツールでは識別のために任意の group を指定できます。get_node_config と履歴ツールでは、group が省略されると自動的にグループを検索します（git 出力の single_repo ではグループが保存パスの一部となるため、oxidized-web では指定が必要です）。グループのないノードは default グループとして表示され、default を指定しても「グループなし」として扱われます。search_configs のグループの絞り込みは、list_nodes と同じ方法（完全一致）です。Oxidized はノード名または IP アドレスだけでバックアップをキューに追加するため、trigger_node_backup ではグループを指定できません。
• 大規模なインベントリの絞り込み：list_nodes ／ get_backup_stats の group と model は Oxidized 自体が絞り込みます。グループは完全一致（list_nodes に表示されるとおり、大文字と小文字を区別）である必要があります。そのため、グループ名を間違えるとインベントリ全体をダウンロードせず、結果は何も返されません。組み込みモデル名では大文字と小文字が区別されません（ios と IOSXE エイリアスは、Oxidized のモデルカタログに基づき IOS として送信されます）。カスタムモデル名は正確に入力する必要があります。どちらの絞り込みも、インベントリ全体のダウンロードにフォールバックすることはありません。
• 検索は2段階で実行されます。oxidized-web の conf_search が一致するデバイスを見つけ（サーバー側ですべての設定を読み取るため、大規模なインストールでは時間がかかる場合があります）、その後、一致した設定だけを取得して該当行を抽出します。max_nodes は取得数の上限です。バックアップが一度も実行されていないノード（一致する可能性のあるプレースホルダーテキストを持つノード）は、取得数に含めずスキップされます。サーバー側の処理には OXIDIZED_TIMEOUT ではなく、OXIDIZED_SEARCH_TIMEOUT（デフォルトは300秒）が使用されます。パターンはサーバー側では Ruby の正規表現として、ローカルでは Python の正規表現として、行単位で処理されるため、一般的な構文を使用してください。
• バックアップは非同期です：trigger_node_backup はデバイスをキューの先頭に移動します。結果は get_node で確認してください。
• エラー：oxidized-web は不明なノード名に対して HTTP 500 を返します。RACK_ENV=production で実行されている場合、理由は表示されません。そのため、ノードのルートで発生した500エラーには、ノード名が不明である可能性を示すヒントが付けられます。

🐳 Docker の使用

簡単にデプロイできるよう、GitHub Packages で Docker イメージを利用できます。

docker pull ghcr.io/mhajder/oxidized-mcp:latest

docker run --rm -p 8000:8000 \
  -e OXIDIZED_URL=http://oxidized:8888 \
  -e MCP_HTTP_BEARER_TOKEN=your-secret-token \
  ghcr.io/mhajder/oxidized-mcp:latest

イメージはデフォルトで、ポート8000のHTTP Streamableトランスポート（http://localhost:8000/mcp）を使用します。

🤝 貢献

貢献を歓迎します。開発環境のセットアップ、チェック、コミットメッセージの形式については、CONTRIBUTING.md をご覧ください。バグや機能リクエストには、イシューテンプレートをご利用ください。

セキュリティ上の問題を発見した場合は、SECURITY.md の説明に従って、非公開でご報告ください。

📜 ライセンス

MIT License の詳細については、LICENSE をご覧ください。