Atera

Atera MCP Server

Atera RMM API と連携するための Model Context Protocol（MCP）サーバーです。効率的なツール検出とコンテキストのオーバーヘッド削減を実現する、決定木アーキテクチャを実装しています。

ワンクリックデプロイ

重要

クリックする前にご確認ください： このサーバーは @wyre-technology/node-atera に依存しており、 GitHub Packages npm レジストリでホストされています。GitHub Packages では 匿名アクセスができません。パッケージが公開されていても、npm install のたびに トークンが必要です。クラウドビルダーが代わりに npm install を実行するため、 トークンを渡す必要があります。渡さない場合、ビルドは npm error 401 Unauthorized ... npm.pkg.github.com で失敗します。

1. read:packages スコープを持つ GitHub Personal Access Token を作成します （クラシックトークン）。 GitHub アカウントであればどれでも構いません。公開パッケージの読み取りに WYRE-AI org のメンバーである必要はありません。
2. デプロイフローで求められたら、ビルド変数としてトークンを追加します。
   • Cloudflare Workers → ビルド変数 NODE_AUTH_TOKEN に PAT を設定します （Workers → Settings → Build → Variables and Secrets）。
   • DigitalOcean App Platform → 暗号化された環境変数 GITHUB_TOKEN を設定し、 スコープを Build Time にして PAT を指定します（.do/app.yaml ではすでに宣言されています）。

メモ

DigitalOcean のターゲットは完全な Docker イメージをビルドし、MCP サーバー全体を HTTP 経由で実行します。運用者にはこの方法を推奨します。Cloudflare Workers のターゲットは現在、簡易的なエントリーポイントのスタブです（/mcp ルートは 501 Not Implemented を返します）。ゲートウェイ形式のデプロイに最適です。完全な セルフホストサーバーを使用する場合は、DigitalOcean または事前ビルド済みコンテナーイメージ （ghcr.io/wyre-ai/atera-mcp）を推奨します。

特徴

• 決定木ナビゲーション：ツールはドメイン（顧客、エージェント、チケット、アラート、連絡先）ごとに整理されています。まずドメインに移動し、次にドメイン固有のツールを使用します。
• クライアントの遅延読み込み：Atera クライアントは初めて必要になったときにのみインスタンス化されるため、起動時間を短縮できます。
• API を完全に網羅：顧客管理、デバイス／エージェントの監視、チケット操作、アラート処理、連絡先管理に対応しています。
• レート制限への対応：node-atera クライアント経由でレート制限を組み込みで処理します（700 req/min）。
• インタラクティブなチケットカード（MCP Apps）：atera_tickets_get は MCP Apps ホスト（Claude Desktop/web）でインタラクティブなカードとして表示されます。カード内の「コメントを追加」操作は atera_tickets_add_comment を介して往復処理されます（デフォルトでは内部専用）。他のホストでのプレーンな JSON の動作は変わりません。カードはデフォルトでニュートラルなデザインで、window.__BRAND__ の注入または MCP_BRAND_* 環境変数（MCP_BRAND_NAME、MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、MCP_BRAND_BG、MCP_BRAND_TEXT）を使ってブランド設定できます。再ビルドは不要です。

インストール

このパッケージは GitHub Packages npm レジストリで公開されています。公開パッケージであってもトークンが必要です。一度認証してからインストールしてください。

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install @wyre-ai/atera-mcp

リポジトリの .npmrc では、すでに @wyre-ai スコープが GitHub Packages を参照し、 トークンを NODE_AUTH_TOKEN から読み込むように設定されているため、追加の設定は不要です。

または、ソースからビルドします。

git clone https://github.com/WYRE-AI/atera-mcp.git
cd atera-mcp
npm install
npm run build

設定

.env.example をコピーし、以下の変数を設定してください。

変数	必須	説明
ATERA_API_KEY	stdio および AUTH_MODE=env の場合	Admin > Data management > API で取得した Atera API トークンまたは従来の API キーです。JWT トークンは Authorization: Bearer として、従来のキーは X-API-KEY として送信されます。Compose ゲートウェイサービスはこの変数を読み込みません。
MCP_TRANSPORT	いいえ	stdio（デフォルト）または http
AUTH_MODE	いいえ	gateway（Docker イメージおよび Compose のデフォルト）または env。ゲートウェイモードでは各 /mcp リクエストに X-Atera-API-Key が必要で、ATERA_API_KEY へのフォールバックは行いません。env では S2S 認証が成功した後にのみ、この変数を使用します。
CONDUIT_S2S_SECRET	HTTP では必須	サービス間シークレットです。openssl rand -hex 32 で生成してください。空の場合、または既知のプレースホルダー（changeme、your-s2s-secret、secret、placeholder などの公開例）の場合、HTTP サーバーはエラーをログに記録してゼロ以外の終了コードで終了します。これが設定されていない場合、Compose は起動しません。実際の値をコミットしないでください。この値がログに記録されることはありません。
MCP_ALLOW_INSECURE_DEV	いいえ	CONDUIT_S2S_SECRET なしで HTTP を起動する場合に限り、ローカル開発用として 1 を設定します。プロセスは警告をログに記録し、X-Gateway-S2S を必須とせず、MCP_HTTP_HOST により広いアドレスが指定されていても、リスナーを 127.0.0.1 に固定します。既知のプレースホルダーシークレットは引き続き拒否されます。
MCP_HTTP_HOST	いいえ	MCP_TRANSPORT=http の場合のバインドアドレスです。未設定の場合は 127.0.0.1 がデフォルトです。CONDUIT_S2S_SECRET が設定されている場合、この値が使用されます。コンテナイメージでは 0.0.0.0 が設定されます。
MCP_HTTP_PORT	いいえ	HTTP ポートです。デフォルトは 8080 です。

/health は認証なしでアクセスでき、認証情報を読み取りません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

HTTP 認証

MCP_TRANSPORT=http かつ CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S を含める必要があります。検証処理は src/s2s-verify.ts の verifyS2sHeader です。ヘッダー値は t=<unix seconds>,v1=<hex> で、hex は CONDUIT_S2S_SECRET をキーとして、文字列 t=<unix seconds> をそのまま HMAC-SHA256 でハッシュ化した値（小文字の 16 進数 64 文字）です。タイムスタンプはサーバーの時刻から 300 秒以内でなければなりません。ヘッダーがない場合、または無効な場合は、ベンダーの認証情報が読み取られる前に HTTP 401 が返されます。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-Atera-API-Key: $ATERA_API_KEY" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway の場合、/mcp には X-Atera-API-Key も必要です。このヘッダーが、そのリクエストで使用する唯一の認証情報です。AUTH_MODE=env の場合、署名付きリクエストのヘッダーにキーがないときは、環境変数の ATERA_API_KEY が使用されます。

API キーの取得

1. 管理者として Atera にログインします
2. Admin > Data management > API に移動します
3. API トークン（JWT）を作成するか、従来の API キーをコピーします

JWT トークン（発行者 AteraInterop）は Authorization: Bearer で認証されます。 従来の静的キーは X-API-KEY で認証されます。このサーバーは、インストール済みの node-atera クライアントが引き続き X-API-KEY のみを送信する場合も含め、キーの形式に応じて ヘッダーを選択します。

使用方法

Claude Desktop を使用する場合

claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "atera": {
      "command": "npx",
      "args": ["@wyre-ai/atera-mcp"],
      "env": {
        "ATERA_API_KEY": "your-api-key-here"
      }
    }
  }
}

MCP Gateway を使用する場合

ゲートウェイレジストリで設定します。

{
  "name": "atera-mcp",
  "command": "node",
  "args": ["/path/to/atera-mcp/dist/index.js"],
  "env": {
    "ATERA_API_KEY": "${ATERA_API_KEY}"
  }
}

Docker

イメージはコンテナ内の 0.0.0.0（MCP_HTTP_HOST）でリッスンし、デフォルトで AUTH_MODE=gateway を使用します。ポートをループバックに公開し、実際の S2S シークレットを渡してください。ゲートウェイモードでは、Atera API キーは各リクエストの X-Atera-API-Key として渡され、環境変数からは読み込まれません。

# Generate the secret first: openssl rand -hex 32
docker build -t atera-mcp .
docker run \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  atera-mcp

Compose は CONDUIT_S2S_SECRET が未設定の場合に起動を拒否し、AUTH_MODE を gateway に設定します。また、ATERA_API_KEY を注入せず、127.0.0.1:8080:8080 を公開します。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

シングルテナントの HTTP（AUTH_MODE=env）でも S2S シークレットが必要です。その後、ATERA_API_KEY が使用されます。

docker run \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e ATERA_API_KEY=your-key \
  -p 127.0.0.1:8080:8080 \
  atera-mcp

シークレットなしのローカル HTTP は、開発用に限られます。127.0.0.1 のみでバインドし、警告をログに記録します。ループバック以外の MCP_HTTP_HOST は無視され、その上書きがログに記録されます。

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm start

判断ツリーアーキテクチャ

このサーバーでは、ナビゲーションベースの方法でツールを検出します。

1. 開始：atera_navigate ツールのみが利用可能です
2. ナビゲート：ドメイン（customers、agents、tickets、alerts、contacts）を指定して atera_navigate を呼び出します
3. ツールリストの更新：サーバーは tools.listChanged を宣言し、notifications/tools/list_changed を送信して、クライアントに tools/list を再取得させます
4. ドメインツール：更新後、ドメイン固有のツールが利用可能になります
5. 戻る：atera_back を使用してドメイン選択に戻ります（この場合も notifications/tools/list_changed が送信されます）

このアーキテクチャには、次の利点があります。

• LLM のパフォーマンス向上のため、ツールリストのサイズを削減します
• 関連する操作を論理的にグループ化します
• コンテキストウィンドウの使用量を最小限に抑えます

利用可能なドメイン

顧客

顧客（企業）のレコードを管理します。

• atera_customers_list - ページネーションを使用して顧客を一覧表示します
• atera_customers_get - ID で顧客を取得します
• atera_customers_create - 新しい顧客を作成します

エージェント

Atera エージェントがインストールされたデバイス／エンドポイントを管理します。

• atera_agents_list - オプションの顧客フィルターを指定してエージェントを一覧表示します
• atera_agents_get - ID でエージェントを取得します
• atera_agents_get_by_machine - マシン名でエージェントを取得します

チケット

サービスチケットを管理します。

• atera_tickets_list - フィルターを指定してチケットを一覧表示します
• atera_tickets_get - ID でチケットを取得します
• atera_tickets_create - 新しいチケットを作成します
• atera_tickets_update - 既存のチケットを更新します

アラート

デバイスやエージェントからのアラートを監視します。

• atera_alerts_list - フィルターを指定してアラートを一覧表示します
• atera_alerts_get - ID でアラートを取得します
• atera_alerts_by_agent - エージェントのアラートを一覧表示します
• atera_alerts_by_device - デバイスのアラートを一覧表示します

連絡先

顧客の連絡先を管理します。

• atera_contacts_list - すべての連絡先を一覧表示します
• atera_contacts_get - ID で連絡先を取得します
• atera_contacts_by_customer - 顧客の連絡先を一覧表示します

会話例

User: List all open tickets

Claude: I'll navigate to the tickets domain and list open tickets.
[Calls atera_navigate with domain: "tickets"]
[Calls atera_tickets_list with ticketStatus: "Open"]

Result: Found 15 open tickets...

開発

# Install dependencies
npm install

# Build
npm run build

# Run in development
npm run dev

# Type check
npm run typecheck

# Lint
npm run lint

# Test
npm run test

API レート制限

Atera API のリクエスト上限は毎分 700 件です。基盤となる node-atera クライアントは、リクエストをキューに入れてレート制限を自動的に処理します。

ライセンス

Apache-2.0

コントリビューション

コントリビューションを歓迎します。コントリビューションガイドラインをお読みのうえ、メインブランチに PR を提出してください。