Skip to main content
Glama
deenesjakoruzh
pete-builds

mcp-unifi

by pete-builds
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

mcp-unifi

CI Release License: MIT Python MCP Coverage

セルフホスト型UniFiゲートウェイ管理用のMCPサーバーです。デバイス、ネットワーク/VLAN、WiFi SSID（フルCRUD）、ファイアウォールルール（フルCRUD）、スイッチポートプロファイル、接続クライアントを網羅する15種類のツールに加え、分離されたIoTサブネット（VLAN、SSID、ファイアウォールブロック）を単一の呼び出しでプロビジョニングし、部分的な失敗時には自動ロールバックを行う create_iot_network ツールを提供します。

FastMCPとStreamable HTTPトランスポート上に構築されています。ローカルAPIキーを使用して、UCG-Fiber、UDM Pro、またはその他のUniFi OSゲートウェイと通信します。サイトマネージャーやクラウドアカウントは不要です。

すべてのツールはJSONを返します。エラーは構造化された {"error": "...", "stub_mode": bool} オブジェクトとして返されるため、ゲートウェイの不調によってMCPループがクラッシュすることはありません。

理由

現在のUniFi自動化の多くは、コントローラーUIのクリック操作、壊れやすい場当たり的なスクリプトの作成、または重量級のコミュニティSDKの導入を必要とします。mcp-unifiは、MCP対応クライアント（Claude Code、Claude Desktop、カスタムエージェント）に対して、毎週行うような操作（IoT VLANの立ち上げ、ファイアウォールルールの追加、SSIDの監査、採用済みデバイスのリスト表示など）のための、小さく、焦点を絞った、型安全なインターフェースを提供します。

複合ツールである create_iot_network を使用すれば、15ステップかかるUIワークフローを単一のツール呼び出しに短縮できます。

Related MCP server: UniFi MCP

クイックスタート

公開されているイメージをプルして実行します：

docker run --rm \
  -p 3714:3714 \
  -e STUB_MODE=true \
  ghcr.io/pete-builds/mcp-unifi:0.2.0

サーバーはデフォルトでスタブモードで起動します。これは現実的なモックデータを返し、UniFiハードウェアを必要としません。Claude Codeに登録します：

claude mcp add unifi --transport http --scope user --url http://localhost:3714/mcp

次に、Claude Codeに「私のUniFiデバイスをリストして」と尋ねると、2つのスタブ化されたデバイスが表示されるはずです。

実際のゲートウェイと通信するには、認証情報を渡し、スタブモードをオフにします：

docker run --rm \
  -p 3714:3714 \
  -e STUB_MODE=false \
  -e UNIFI_HOST=192.168.1.1 \
  -e UNIFI_API_KEY=<your-local-api-key> \
  ghcr.io/pete-builds/mcp-unifi:0.2.0

APIキーは、ゲートウェイの 設定 → コントロールプレーン → インテグレーション から生成してください。

ツールリファレンス

ツール

シグネチャ

機能

list_devices

()

採用済みのゲートウェイ、AP、スイッチを、状態、稼働時間、無線ごとの情報とともにリストします。

list_networks

()

設定済みのすべてのネットワーク/VLAN（サブネット、DHCP範囲、VLAN ID）をリストします。

create_vlan

(name, vlan_id, subnet, dhcp_start?, dhcp_stop?, purpose?)

新しいVLANタグ付きネットワークを作成します。

update_vlan

(network_id, updates)

既存のVLANのフィールドをパッチします。

delete_vlan

(network_id)

VLANを削除します。

list_wlans

()

すべてのWiFi SSIDをリストします。

create_wlan

(name, passphrase, network_id, security?, wpa_mode?, is_guest?, hide_ssid?, wlan_band?)

特定のVLANにバインドされた新しいSSIDを作成します。

update_wlan

(wlan_id, updates)

既存のSSIDのフィールド（名前、パスフレーズ、hide_ssidなど）をパッチします。

delete_wlan

(wlan_id)

WiFi SSIDを削除します。

list_firewall_rules

()

すべてのファイアウォールルールをリストします。

create_firewall_rule

(name, ruleset, action, rule_index?, protocol?, src_address?, dst_address?, src_networkconf_id?, dst_networkconf_id?, enabled?)

ファイアウォールルールを作成します。

delete_firewall_rule

(rule_id)

ファイアウォールルールを削除します。

list_port_profiles

()

スイッチポートプロファイル（PoEモード、ネイティブVLAN、転送）をリストします。

list_clients

()

現在接続されている無線および有線クライアント（MAC、ホスト名、IP、信号強度/満足度、APまたはスイッチポート、稼働時間）をリストします。

create_iot_network

(name, vlan_id, passphrase, main_lan_subnet?, subnet?, isolate?, hide_ssid?)

一括作成：VLAN + SSID + 分離ルール。失敗時はロールバックします。

すべてのツールはJSON文字列を返します。エラーは構造化された {"error": "...", "stub_mode": bool} オブジェクトとして返されるため、ClaudeはMCPループをクラッシュさせることなく失敗を表示できます。

スタブモードとリアルモード

モード

使用場面

動作

スタブ (STUB_MODE=true, デフォルト)

開発、デモ、ハードウェア到着前のClaudeフロー構築

1つのゲートウェイ、1つのAP、1つのネットワーク、1つのSSID、1つのファイアウォールルール、2つのポートプロファイルでシードされたメモリ内ステートマシン。作成/更新/削除はコンテナの存続期間中保持されます。再起動でリセットされます。

リアル (STUB_MODE=false)

UCG-Fiber/UDM/その他のUniFi OSゲートウェイでの本番運用

ローカルAPIキーを使用してゲートウェイとHTTPS通信します。UNIFI_HOST と UNIFI_API_KEY が必要です。

モードの切り替えは設定変更であり、コード変更ではありません。同じ11個のツール、同じレスポンス形式です。

設定

すべての設定は環境変数（および存在する場合は .env ファイル）から読み込まれます。設定は起動時にPydanticによって検証され、無効な値がある場合は役立つメッセージとともに即座に失敗します。

変数

型

デフォルト

必須

メモ

STUB_MODE

bool

true

いいえ

false の場合、リアルモードの認証情報が必要です。

UNIFI_HOST

string

""

リアルモードのみ

ゲートウェイのIPまたはホスト名（スキームなし）。

UNIFI_PORT

int

443

いいえ

ゲートウェイのHTTPSポート。

UNIFI_SITE

string

default

いいえ

コントローラーのサイト識別子。

UNIFI_API_KEY

string

""

リアルモードのみ

設定 → コントロールプレーン → インテグレーション からのローカルAPIキー。

UNIFI_VERIFY_SSL

bool

false

いいえ

ゲートウェイに正規の証明書をインストールしている場合は true に設定します。

IOT_SUBNET_TEMPLATE

string

10.0.{vlan_id}.0/24

いいえ

{vlan_id} プレースホルダーを含める必要があります。

IOT_DHCP_START_OFFSET

int (2-254)

100

いいえ

IoT /24 内の最初のDHCPリースオフセット。

IOT_DHCP_STOP_OFFSET

int (2-254)

200

いいえ

IoT /24 内の最後のDHCPリースオフセット。

MCP_HOST

string

0.0.0.0

いいえ

バインドアドレス。

MCP_PORT

int

3714

いいえ

リッスンポート。

LOG_LEVEL

enum

INFO

いいえ

DEBUG, INFO, WARNING, ERROR, CRITICAL のいずれか。

LOG_FORMAT

enum

json

いいえ

本番環境は json、ローカル開発は text。

完全な例は .env.example にあります。

MCPクライアントの設定

Claude Code

claude mcp add unifi --transport http --scope user --url http://<host>:3714/mcp

Claude Desktop

claude_desktop_config.json に以下を追加します：

{
  "mcpServers": {
    "unifi": {
      "transport": "streamable-http",
      "url": "http://<host>:3714/mcp"
    }
  }
}

汎用設定

http://<host>:3714/mcp でStreamable HTTPを利用可能です。Streamable HTTPトランスポートをサポートするすべてのMCPクライアント（仕様 2025-03-26以降）が接続できます。

アーキテクチャ

+---------------------+         Streamable HTTP         +---------------------+
|  MCP Client         |  -------------------------->    |  mcp-unifi          |
|  (Claude Code, etc) |  <--------------------------    |  (FastMCP server)   |
+---------------------+                                 +----------+----------+
                                                                   |
                                                                   |  HTTPS + X-API-Key
                                                                   v
                                                        +----------+----------+
                                                        |  UniFi OS Gateway   |
                                                        |  /proxy/network/... |
                                                        +---------------------+

このサーバーは軽量な非同期プロキシです。MCPツール呼び出しをUniFiコントローラーのREST呼び出しに変換し、レスポンスを整形してJSONを返します。状態を保存せず、クラウドへの呼び出しも行わず、着信MCP接続の認証も行いません（信頼できるLAN内で実行してください）。

セキュリティ上の注意

  • UNIFI_API_KEY はコンテナの環境変数内にのみ存在します。ログに記録されることはなく、MCPレスポンスでエコーバックされることもなく、このサーバーによってディスクに書き込まれることもありません。

  • WLANパスフレーズは、すべてのツールレスポンスの出力時に（スタブモードであっても）スクラブ（[REDACTED]）されます。

  • コンテナは UID 1000 で実行され、シェルやホームディレクトリはなく、読み取り専用のルートファイルシステム（/tmp は tmpfs）で、no-new-privileges が設定されています。

  • ベースイメージはダイジェストで固定されています。Pythonの依存関係は、ハッシュロックされた requirements.lock から pip --require-hashes を使用してインストールされます。

  • 公開されているイメージはマルチアーキテクチャ（amd64/arm64）であり、docker/build-push-action を介したビルドの来歴証明とSBOMが含まれています。

  • MCPサーバー自体は認証されていません。信頼できるLAN境界、認証付きのリバースプロキシ、またはTailscale ACLの背後に配置してください。

脆弱性レポートについては、SECURITY.md を参照してください。

開発

Python 3.13+ と Docker が必要です。

# Clone + install dev deps
git clone https://github.com/pete-builds/mcp-unifi.git
cd mcp-unifi
python -m venv .venv && source .venv/bin/activate
pip install --require-hashes -r requirements-dev.lock
pip install -e . --no-deps

# Run the test suite (101 tests, ~95% coverage)
pytest

# Lint and format
ruff check src tests
ruff format src tests

# Type check (mypy strict)
mypy src/mcp_unifi

# Run the server locally in stub mode
python -m mcp_unifi.server

# Or build the image yourself instead of pulling from GHCR
cp docker-compose.example.yml docker-compose.yml
docker compose up --build

テスト

======================= 101 passed in 1.5s =======================

Name                          Stmts  Miss  Branch  BrPart  Cover
-----------------------------------------------------------------
src/mcp_unifi/__init__.py         2     0       0       0   100%
src/mcp_unifi/clients/__init__    3     0       0       0   100%
src/mcp_unifi/clients/stubs.py   70     1       6       0    99%
src/mcp_unifi/clients/unifi.py   82     0      12       0   100%
src/mcp_unifi/config.py          38     1       8       0    98%
src/mcp_unifi/healthcheck.py     18     1       0       0    94%
src/mcp_unifi/logging_setup.py   33     1      12       2    93%
src/mcp_unifi/models.py           6     0       0       0   100%
src/mcp_unifi/server.py         232    15      70       5    92%
-----------------------------------------------------------------
TOTAL                           484    19     108       7    95%

CIは、80%以上のカバレッジ、ruff lint、ruff format、mypy strict、およびHIGHまたはCRITICALの発見で失敗するTrivy fs+imageスキャンによってゲートされています。

依存関係の更新

requirements.lock および requirements-dev.lock ファイルはハッシュ固定されています。requirements.in（または requirements-dev.in）を編集し、再生成します：

uv pip compile requirements.in --output-file requirements.lock --generate-hashes --python-version 3.13
uv pip compile requirements-dev.in --output-file requirements-dev.lock --generate-hashes --python-version 3.13

Dependabotが、requirements.in レベルの更新とDockerベースイメージのダイジェスト更新のために毎週PRを作成します。

謝辞

UniFiコントローラーのエンドポイントパスは、sirkirby/unifi-mcp プロジェクトを参照しました。そのリポジトリはAPIサーフェスの調査資料として使用されましたが、コードはコピーされていません。ここでの実装は、実績のあるForgeパターンに従った独立したFastMCP + httpxビルドです。

ライセンス

MIT。

貢献

Issueやプルリクエストを歓迎します。PRを開く前に：

  1. ruff check、ruff format --check、mypy src/mcp_unifi がクリーンであることを確認してください。

  2. テストを追加または更新し、カバレッジを80%以上に維持してください。

  3. ローカルで pytest を実行し、スイートがパスすることを確認してください。

  4. CHANGELOG.md の [Unreleased] 見出しの下を更新してください。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityActive
ResponsivenessSlow

Resources

Related MCP Connectors

Related MCP Servers

  • unifi-mcp

    kjmagnan1s
    A
    license
    Not graded
    quality
    D
    maintenance
    A safety-first MCP server for managing UniFi networks, exposing 17 tools for telemetry, diagnostics, and guarded mutations with dry-run previews and confirm requirements.
    14
    MIT

  • go-unifi-mcp

    claytono
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for UniFi Network Controller enabling AI assistants to manage UniFi infrastructure via natural language. It supports firewall rules, IPv6, and uses lazy/eager tool modes to minimize context usage.
    6
    Mozilla Public 2.0