axis-camera-mcp

MCP（Model Context Protocol）サーバーで、LLM（Claude Code/Desktop）がVAPIX（AxisのHTTP/JSONカメラAPI）を介してAxisネットワークカメラと通信できるようにします。VLCでのライブストリーム表示、パン/チルト/ズームの制御、イメージセンサー設定（明るさ、露出、ゲイン、ホワイトバランス）の調整、スナップショットの撮影、テキスト/画像オーバーレイの追加、時計の取得/設定、ローカルカメラのユーザーアカウント管理、ライトの制御が可能です。

ローカルネットワーク上のAXIS M3057-PLVE Mk IIに対して構築され、実機で検証済みです。ライブでテスト済みの内容と未テストの内容の正確な内訳はdocs/live-verification-checklist.mdを参照してください。また、この特定のカメラの確認済みの制限事項についてはdocs/open-questions.mdを参照してください。この固定カメラモデルでは、PTZコマンドは成功し、報告される位置も更新されますが、実際の視覚的なパン/チルト/ズーム効果は発生しません。

アーキテクチャ

axis_camera_mcp/
  config.py            Loads camera host/username/password from config.json
  vapix/
    session.py          requests.Session + HTTP Digest auth
    jsonrpc.py           Client for VAPIX's modern JSON-RPC-style APIs
    legacy.py             Client for VAPIX's legacy query-param/plain-text CGIs
    client.py              VapixClient facade - the only thing tools/* imports
    exceptions.py
  vlc_launcher.py       Starts/stops the local VLC install to view the RTSP stream
  rag/                  Local knowledge base: VAPIX docs + this project's own
                        live-verified findings, hybrid BM25+embedding search
                        (see "Knowledge base (RAG)" below)
  app.py / context.py  Shared FastMCP instance + lazy VapixClient/VlcLauncher/
                        HybridRetriever singletons
  tools/                One module per capability, each registering @mcp.tool()s
  server.py             Entrypoint: import tools, preload_rag(), mcp.run()
tests/
  test_*.py             Unit tests, mocked HTTP, no live camera needed
  manual/                Plain scripts (not pytest) exercised against the real camera
docs/
  live-verification-checklist.md   One row per tool - what's actually been tested live
  open-questions.md                Confirmed limitations and things not yet tried

このカメラには2つのVAPIXリクエストスタイルが併存しており、クライアント層はその違いをツールコードに漏らすことなく両方を処理します：

• モダンなJSON-RPCスタイル（api-discovery、basicdeviceinfo、streamprofile、lightcontrol、time.cgi、dynamicoverlay）：POST JSONボディ{"apiVersion", "method", "params"}、レスポンスは{"data"}または{"error"}。

• レガシーなクエリパラメータ/プレーンテキストCGI（com/ptz.cgi、com/ptzconfig.cgi、pwdgrp.cgi、usergroup.cgi、jpg/image.cgi）：クエリパラメータ付きのプレーンなGET。レスポンスはプレーンテキスト（場合によってはkey=value行）または、スナップショットエンドポイントの場合は生のJPEGバイトです。

セットアップ

認証情報は設定ファイルに保存され、コードや環境変数には決して保存されません：

copy config.example.json config.json
notepad config.json   # fill in host/username/password

config.jsonはgitignoreされており、コミットされることはありません。

py -m venv .venv
.venv\Scripts\python -m pip install -e ".[dev]"

実行

.venv\Scripts\python -m axis_camera_mcp.server

ナレッジベース（RAG）

ローカルでオフラインのナレッジベースにより、LLMは実際のVAPIX APIドキュメントと、このプロジェクト自身が苦労して得た実機検証済みの知見（ドキュメント化されていない必須フィールド、実機での試行錯誤によってのみ確認された実際のパラメータ値など）を検索でき、毎回推測したり再導出したりする必要がありません。

すべてオープンソース、すべてローカル - 有料APIもベクターDBサービスも不要です：

• クローラー（rag/crawler.py）：developer.axis.com（サーバーレンダリングされたDocusaurusサイト - ヘッドレスブラウザ不要）に対する素のrequests + BeautifulSoupに加え、このプロジェクト自身のREADME/docs/vapix/*.pyをローカルソースとして使用します。

• チャンキング（rag/chunker.py）：段落を考慮し、~700文字・100文字オーバーラップ。

• 検索（rag/retriever.py）：ハイブリッド - BM25（rank-bm25、streamProfileNameのような正確なキーワード一致）と高密度埋め込み（sentence-transformers、all-MiniLM-L6-v2、CPUのみ、言い換えられた質問用）を、相互ランク融合（reciprocal rank fusion）で組み合わせます。ベクターストアにはプレーンなnumpy .npzファイルを使用します（数百チャンクであれば総当たりコサイン検索はマイクロ秒単位になり、本格的なベクターDB依存にする価値はありません）。

• トラッキング（rag/tracking.py）：ローカルのSQLiteファイルに、すべての取り込み実行（ソースごとのチャンク数/文字数、ok/エラーステータス）とすべてのクエリ（テキスト、結果、スコア）を記録します - 直接、またはrag_statsツール経由で検査可能です。

セットアップ：sentence-transformersはtorchを引き込み、本当に重いインストールになります。CPUのみのマシンでは、デフォルトで解決されるビルドよりもはるかに小さく抑えるため、最初にCPU専用のwheelを明示的にインストールしてください：

.venv\Scripts\python -m pip install torch --index-url https://download.pytorch.org/whl/cpu
.venv\Scripts\python -m pip install -e ".[dev]"

インデックスの構築/更新（別途手動で実行するステップ - サーバー起動時に自動実行されることはないため、起動は高速でネットワーク呼び出しも発生しません）：

.venv\Scripts\python -m axis_camera_mcp.rag.ingest

axis_camera_mcp/rag/sources.jsonを編集してドキュメントページやローカルファイルを追加/削除し、上記のコマンドを再実行します。埋め込みモデル（~80MB）は初回実行時にHugging Face Hubから一度だけダウンロードされ、以降はキャッシュされます。その他はすべて完全にオフラインです。生成されたインデックスファイル（rag/data/*.jsonl、*.npz、*.sqlite3）はgitignoreされています。

search_knowledgeツールとrag_statsツールでクエリを実行します（下記のツールリファレンスを参照）。

Claude Code/Desktopへの登録

{
  "mcpServers": {
    "axis-camera": {
      "command": "<path-to-repo>\\.venv\\Scripts\\python.exe",
      "args": ["-m", "axis_camera_mcp.server"]
    }
  }
}

追加後、ツールが表示されるようにClaude Code/Desktopを再起動してください。

テスト

.venv\Scripts\python -m pytest tests/ --ignore=tests/manual   # unit tests, mocked HTTP
.venv\Scripts\python tests/manual/live_smoke_test.py           # read-only checks against the real camera

tests/manual/のスクリプトはconfig.json内の実カメラと通信します - 重要なカメラに対して実行する前に、各スクリプトが何を行うかを確認してください。live_smoke_test.pyは読み取り専用です。mcp_harness_*.pyスクリプトは完全なMCPツール呼び出しパスを実行します（PTZ移動、時計/タイムゾーン変更、ユーザー追加/削除などの変更操作を含む）- これらはこのプロジェクト自身の実機検証スクリプトでした。参考として扱い、本番カメラに対して気軽に再実行するものではありません。

ツールリファレンス

デバイス/API情報（読み取り専用）：get_device_info、get_supported_apis、get_camera_overview

ストリーミング（ローカルのVLCインストールでライブストリームを表示）：start_stream、stop_stream、get_stream_status、list_stream_profiles

スナップショット（ビデオストリームとは別の単一静止フレーム）：save_snapshot（ファイルのみで、LLMが画像を見ることはありません）、get_snapshot（LLMに直接返され、視界にあるものを説明できます）

PTZ（パン/チルト/ズーム - この特定のカメラでは視覚効果がないことについてはdocs/open-questions.mdを参照）：ptz_move_absolute、ptz_move_relative、ptz_get_position、ptz_save_preset、ptz_goto_preset、ptz_list_presets

イメージセンサー（明るさ/コントラスト/彩度/シャープネス、露出、ゲイン、シャッター、ホワイトバランス - 実際のセンサー/ISP設定であり、PTZのフレーミング/クロップやライトの物理的な照明器とは異なります）：get_image_settings、set_image_appearance、set_exposure_mode、set_exposure_value、set_manual_gain、set_manual_shutter、set_white_balance

オーバーレイ（ビデオストリームに焼き込まれるテキスト/画像）：add_text_overlay、set_text_overlay、add_image_overlay、set_image_overlay、list_overlays、remove_overlay、get_overlay_capabilities

時計：get_clock_info、set_clock、set_timezone

ライト（この特定のカメラにはライトハードウェアがありません - get_light_statusで明確に報告されることで確認済み）：get_light_status、activate_light/deactivate_light、enable_light/disable_light、set_light_intensity、get_valid_intensity、set_light_auto_mode

ユーザー - 変更操作にはconfirm: trueが必要です。これは実際のセキュリティ影響がある唯一の領域です：list_users（特権を持つ呼び出し元に対して、すべてのアカウントをその権限グループとともに返します）、add_user、update_user、remove_user

ナレッジベース（上記の「ナレッジベース（RAG）」を参照）：search_knowledge（VAPIXドキュメントとこのプロジェクト自身の実機検証済みの知見に対するハイブリッドBM25+埋め込み検索。ソースの引用とスコア付き）、rag_stats（何が、どこから、いつインデックスされたか、および最近のクエリ履歴 - インデックスにrag.ingestの実行が必要かどうかを明確に示します）

安全性

ユーザーアカウントの変更操作（add_user、update_user、remove_user）には明示的なconfirm: trueツール引数が必要で、これがない場合は明確なエラーが発生します - これは不注意な呼び出しが実際のセキュリティ影響（不正アクセスや偶発的なロックアウト）をもたらす唯一の領域です。その他すべて（PTZ、ライト、時計、ストリーミング、オーバーレイ、スナップショット）は設計上確認なしです：自由に元に戻せ、ユーザーが直接所有する単一のカメラであり、共有の本番システムではないためです。