go-unifi-mcp

go-unifi-mcp

Go で書かれた、UniFi Network Controller 用の Model Context Protocol（MCP）サーバーです。

概要

go-unifi-mcp は UniFi Network Controller 向けの MCP インターフェースを提供し、AI アシスタントやその他の MCP クライアントが UniFi インフラストラクチャとやり取りできるようにします。

開発の背景

v1 と v2 の両方のファイアウォールルールおよび IPv6 に対応した MCP サーバーが見つからなかったため、これを開発しました。Terraform プロバイダーの開発経験から信頼している go-unifi ライブラリをラップし、生成された API サーフェスを活用しています。サーバーはコントローラー独自の API 定義から生成されるため、UniFi の進化に合わせてツールの対応範囲を最新の状態に保ちやすくなっています。

UniFi コントローラーのバージョン管理

このプロジェクトでは、go-unifi が固定しているものと同じ UniFi Controller バージョンを対象にツールを生成します。go-unifi が対応するコントローラーバージョンを更新すると、それに合わせてフィールド定義とツールのメタデータを再生成します。同じコントローラーのバージョン範囲に対応しています。詳しくは、go-unifi の コントローラー対応範囲をご覧ください。

インストール

バイナリ（GitHub Releases）

ビルド済みバイナリはリリースページからダウンロードできます。macOS と Linux（amd64/arm64）用のバイナリを提供しています。

# macOS (Apple Silicon)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_darwin_arm64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

# macOS (Intel)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_darwin_amd64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

# Linux (amd64)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_linux_amd64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

# Linux (arm64)
curl -L https://github.com/claytono/go-unifi-mcp/releases/latest/download/go-unifi-mcp_linux_arm64.tar.gz | tar xz
sudo mv go-unifi-mcp /usr/local/bin/

Homebrew

claytono/homebrew-tap タップから入手できます。

brew install claytono/tap/go-unifi-mcp

Nix

# Run without installing
nix run github:claytono/go-unifi-mcp

# Install to your profile
nix profile install github:claytono/go-unifi-mcp

Docker

マルチアーキテクチャイメージ（amd64/arm64）は GitHub Container Registry に公開されています。

# Latest (pinned to most recent release, rebuilt on base image updates)
docker pull ghcr.io/claytono/go-unifi-mcp:latest

# Edge (built from main on every merge, unstable)
docker pull ghcr.io/claytono/go-unifi-mcp:edge

Go Install

go install github.com/claytono/go-unifi-mcp/cmd/go-unifi-mcp@latest

設定

UniFi の認証情報

サーバーには UniFi Network Controller へのアクセスが必要です。次の 2 つの認証方法に対応しています。

1. API キー（推奨）：UniFi コントローラーの Settings > Control Plane > Integrations で API キーを作成します。UNIFI_HOST と UNIFI_API_KEY を設定してください。

2. ユーザー名／パスワード：ローカル管理者アカウントを使用します。UNIFI_HOST、UNIFI_USERNAME、UNIFI_PASSWORD を設定してください。

Claude Desktop

claude_desktop_config.json に追加します。

バイナリを使用する場合：

{
  "mcpServers": {
    "unifi": {
      "command": "/usr/local/bin/go-unifi-mcp",
      "env": {
        "UNIFI_HOST": "https://your-controller:443",
        "UNIFI_API_KEY": "your-api-key"
      }
    }
  }
}

Docker を使用する場合：

{
  "mcpServers": {
    "unifi": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "UNIFI_HOST",
        "-e",
        "UNIFI_API_KEY",
        "ghcr.io/claytono/go-unifi-mcp:latest"
      ],
      "env": {
        "UNIFI_HOST": "https://your-controller:443",
        "UNIFI_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add unifi -- go-unifi-mcp

その後、claude を実行する前に、シェルで必要な環境変数を設定してください。

環境変数

変数	必須	デフォルト	説明
UNIFI_HOST	はい	—	UniFi コントローラーの URL
UNIFI_API_KEY	*	—	API キー（推奨する認証方法）
UNIFI_USERNAME	*	—	パスワード認証に使用するユーザー名
UNIFI_PASSWORD	*	—	パスワード認証に使用するパスワード
UNIFI_SITE	いいえ	default	UniFi サイト名
UNIFI_VERIFY_SSL	いいえ	true	SSL 証明書を検証するかどうか
UNIFI_LOG_LEVEL	いいえ	error	go-unifi クライアントのログレベル
UNIFI_TOOL_MODE	いいえ	lazy	ツール登録モード

* UNIFI_API_KEY、または UNIFI_USERNAME と UNIFI_PASSWORD の両方を設定する必要があります。

ログレベル

UNIFI_LOG_LEVEL 変数は、基盤となる go-unifi クライアントライブラリのログ出力を制御します。デフォルトは error です。これは、クライアントが INFO メッセージを stderr に出力し、stdout／stderr 上の JSON を解析する mcp-cli などのツールに干渉する可能性があるためです。

レベル	説明
disabled	ログ出力なし
trace	最も詳細なログ。通信の詳細を含みます
debug	デバッグメッセージ
info	情報メッセージ
warn	警告のみ
error	エラーのみ（デフォルト）

ツールモード

このサーバーは、 unifi-network-mcp で確立されたパターンに従い、2 つのツール登録モードをサポートしています。

モード	ツール数	コンテキストサイズ	説明
lazy	3	~200 tokens	メタツールのみ（デフォルト、LLM に推奨）
eager	252	~55K tokens	すべてのツールを直接登録

遅延モード（デフォルト）では、コントローラー API から生成された 252 個の UniFi 操作にアクセスできるメタツールを 3 つだけ登録します。

• tool_index - カテゴリまたはリソースでツールカタログを検索／絞り込み
• execute - 名前と引数を指定して任意のツールを実行
• batch - 複数のツールを並列実行

これにより、すべての機能を維持しながら、コンテキストウィンドウの使用量を大幅に削減できます。LLM はまずインデックスを照会して関連するツールを探し、その後ディスパッチャー経由で実行します。

一括モードでは、252 個のツールをすべて直接登録します。LLM 以外のクライアントやデバッグには便利な場合がありますが、コンテキストを大幅に消費します。

更新のセマンティクス： 更新では、コントローラー API に対して読み取り・変更・書き込みのフローを使用します。現在のリソースを取得してフィールドをマージし、オブジェクト全体を送信します。これにより、指定されていないフィールドがクリアされることを防げますが、アトミックではありません。また、UniFi API は etag やリビジョン ID を公開していないため、同時更新が競合する可能性があり（最後の書き込みが優先されます）、実際には問題になる可能性は低いものの、留意が必要です。

ID の解決

UniFi API からの応答には、不透明な ID 参照（例：network_id、usergroup_id、networkconf_id）が含まれます。デフォルトでは、サーバーは参照先のリソースを検索して、人間が読み取れる名前に解決し、同階層の _name フィールドを追加します。

{
  "src_networkconf_id": "609fbf24e3ae433962e000de",
  "src_networkconf_name": "IOT"
}

解決にはリクエストごとのキャッシュを使用するため、ネットワークを参照するファイアウォールルールを 100 件一覧表示しても、追加で呼び出される ListNetwork API は 1 回だけです。通常のオーバーヘッドは、参照されるリソースの種類数に応じて 10～40ms です。

特定の呼び出しで解決を無効にするには、ツールの引数に "resolve": false を渡します。

クエリパラメーター

すべての一覧表示操作では、結果のフィルタリングと射影を行うオプションの後処理パラメーターをサポートしています。

filter — フィールド値で項目を照合します。次の 3 つの演算子をサポートしています。

// Exact match
{"filter": {"type": "usw"}}

// Substring match (case-insensitive)
{"filter": {"name": {"contains": "office"}}}

// Regular expression (RE2 syntax: https://github.com/google/re2/wiki/Syntax)
{"filter": {"name": {"regex": "^ap-.*"}}}

// Multiple conditions (ANDed together)
{"filter": {"type": "uap", "name": {"contains": "echo"}}}

search — すべての文字列フィールド値を対象に、大文字と小文字を区別せず全文検索します。

{ "search": "living room" }

fields — 応答に含める特定のキーだけを選択します。

{ "fields": ["name", "ip", "mac"] }

パラメーターは組み合わせて使用できます。実行順序は filter → search → fields のため、出力から除外されるフィールドで絞り込むこともできます。

{
  "filter": { "type": "uap" },
  "search": "echo",
  "fields": ["name", "ip"]
}

開発

前提条件

• flakes を有効にした Nix
• direnv（任意ですが、推奨）

開発

# Clone the repository
git clone https://github.com/claytono/go-unifi-mcp.git
cd go-unifi-mcp

# Enter the development environment
nix develop
# Or with direnv:
direnv allow

# Install pre-commit hooks
pre-commit install

# Run linters
task lint

# Run tests
task test

# Run tests with coverage
task coverage

利用可能なタスク

task lint        # Run linters via pre-commit
task test        # Run tests
task coverage    # Run tests with coverage checks
task build       # Build the binary
task generate    # Run go generate

mcp-cli でのテスト

開発環境には、MCP サーバーを対話的にテストするための mcp-cli が含まれています。

1. UniFi の認証情報を含む .envrc.local を作成します（git では追跡されません）。

   export UNIFI_HOST="https://your-controller:443"
   export UNIFI_API_KEY="your-api-key"
   # Or use username/password:
   # export UNIFI_USERNAME="admin"
   # export UNIFI_PASSWORD="password"
   

2. バイナリをビルドします。

   task build
   

3. mcp-cli でテストします。

   .mcp_servers.json 設定には、次の 2 つのサーバーエントリーがあります。

   • go-unifi-mcp - 一括モード（252 個のツール）
   • go-unifi-mcp-lazy - 遅延モード（3 つのメタツール）

   一括モード（ツールに直接アクセス）：

   # List tools (shows all 252)
   mcp-cli info go-unifi-mcp
   
   # Call a tool directly
   mcp-cli call go-unifi-mcp list_device '{}'
   mcp-cli call go-unifi-mcp list_network '{"site": "default"}'
   

   遅延モード（メタツール）：

   # List tools (shows only 3 meta-tools)
   mcp-cli info go-unifi-mcp-lazy
   
   # Query the tool index
   mcp-cli call go-unifi-mcp-lazy tool_index '{}'
   mcp-cli call go-unifi-mcp-lazy tool_index '{"category": "list"}'
   mcp-cli call go-unifi-mcp-lazy tool_index '{"resource": "network"}'
   
   # Execute a tool via the dispatcher
   mcp-cli call go-unifi-mcp-lazy execute '{"tool": "list_device", "arguments": {}}'
   
   # Batch execute multiple tools
   mcp-cli call go-unifi-mcp-lazy batch '{"calls": [{"tool": "list_network", "arguments": {}}, {"tool": "list_device", "arguments": {}}]}'
   

クレジット

このプロジェクトは、次のプロジェクトを基盤としています。

• go-unifi - UniFi Network Controller 用の Go クライアントライブラリ
• unifi-network-mcp - このプロジェクトの着想元となった、UniFi 用の Python MCP サーバー
• mcp-go - Model Context Protocol 用の Go SDK

ライセンス

MPL-2.0