OpenClaw MCP Server

OpenClaw MCP サーバー

🦞 OpenClaw の AI アシスタント連携用 Model Context Protocol（MCP）サーバーです。

デモ

作成した理由

こんにちは！OpenClaw とのやり取りをメッセージングチャネルだけに頼りたくなかったので、この MCP サーバーを作成しました。特に魅力を感じたのは、OpenClaw を Claude のウェブ UI に接続できることです。つまり、チャットから Claw ボットにタスクを委任でき、あとはボットがすべて処理してくれます。たとえば、Claude Code を起動して問題を修正することもできます。

ある AI アシスタントが、別の AI アシスタントを統括するようなものです。なかなか面白いと思いませんか？

クイックスタート

Docker（推奨）

リリースごとに、ビルド済みのイメージが GitHub Container Registry に公開されます。

docker pull ghcr.io/freema/openclaw-mcp:latest

docker-compose.yml を作成します。

services:
  mcp-bridge:
    image: ghcr.io/freema/openclaw-mcp:latest
    container_name: openclaw-mcp
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - OPENCLAW_URL=http://host.docker.internal:18789
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - OPENCLAW_AGENT_ID=${OPENCLAW_AGENT_ID:-}
      - OPENCLAW_MODEL=openclaw
      - MCP_CLIENT_ID=openclaw
      - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
      - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
      - MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
      - TRUST_PROXY=1
      - CORS_ORIGINS=https://claude.ai
    extra_hosts:
      - "host.docker.internal:host-gateway"
    read_only: true
    security_opt:
      - no-new-privileges

シークレットを生成して起動します。

export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
export OPENCLAW_GATEWAY_TOKEN=your-gateway-token
docker compose up -d

次に Claude.ai でカスタム MCP コネクターを追加し、https://your-domain.com/mcp を指定して、MCP_CLIENT_ID=openclaw と MCP_CLIENT_SECRET を設定します。

重要： コネクターの URL は 必ず /mcp で終わる必要があります。これは Streamable HTTP エンドポイントです。ドメインのみ（https://your-domain.com）を指定するとサーバーのルートにアクセスし、OAuth の完了後に 404 が返されます。

ヒント： 本番環境では latest ではなく、特定のバージョンを指定してください。例：ghcr.io/freema/openclaw-mcp:1.1.0

ローカル（Claude Desktop）

npx openclaw-mcp

Claude Desktop の設定に追加します。

{
  "mcpServers": {
    "openclaw": {
      "command": "npx",
      "args": ["openclaw-mcp"],
      "env": {
        "OPENCLAW_URL": "http://127.0.0.1:18789",
        "OPENCLAW_GATEWAY_TOKEN": "your-gateway-token",
        "OPENCLAW_AGENT_ID": "main",
        "OPENCLAW_MODEL": "openclaw",
        "OPENCLAW_TIMEOUT_MS": "300000"
      }
    }
  }
}

Docker を使わずにリモート接続（Claude.ai）

MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=your-secret \
  MCP_ISSUER_URL=https://mcp.your-domain.com \
  CORS_ORIGINS=https://claude.ai OPENCLAW_GATEWAY_TOKEN=your-gateway-token \
  npx openclaw-mcp --transport http --port 3000

重要： リバースプロキシ（Caddy、nginx、Traefik、Cloudflare Tunnel など）の背後で実行する場合は、次の設定が必須です。

• MCP_ISSUER_URL（または --issuer-url）には、外部からアクセスできる HTTPS URL を設定してください。設定しない場合、OAuth メタデータに http://localhost:3000 が通知され、クライアントが認証に失敗します。
• TRUST_PROXY=1（または --trust-proxy 1）を設定してください。設定しない場合、express-rate-limit がプロキシの X-Forwarded-For ヘッダーを拒否し、/token が ERR_ERL_UNEXPECTED_X_FORWARDED_FOR でクラッシュします。

推奨： 認可コードの送信先を Claude のコールバックに限定するため、MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback を設定してください。/api/mcp/auth_callback という正確なパスに注意してください。一致判定は完全一致のため、誤ったパスを指定すると OAuth が Unregistered redirect_uri で失敗します（トラブルシューティングを参照）。

詳しくはインストールガイドを参照してください。

アーキテクチャ

┌─────────────────────────────────────────────────────────────────┐
│                         Your Server                             │
│                                                                 │
│  ┌─────────────────┐      ┌─────────────────────────┐          │
│  │   OpenClaw      │      │    OpenClaw MCP         │          │
│  │   Gateway       │◄────►│    Bridge Server        │          │
│  │   :18789        │      │    :3000                │          │
│  │                 │      │                         │          │
│  │  OpenAI-compat  │      │  - OAuth 2.1 auth       │          │
│  │  /v1/chat/...   │      │  - CORS protection      │          │
│  └─────────────────┘      │  - Input validation     │          │
│                           └──────────┬──────────────┘          │
│                                      │                          │
└──────────────────────────────────────┼──────────────────────────┘
                                       │ HTTPS + OAuth 2.1
                                       ▼
                              ┌─────────────────┐
                              │   Claude.ai     │
                              │   (MCP Client)  │
                              └─────────────────┘

利用可能なツール

同期ツール

ツール	説明
openclaw_chat	OpenClaw にメッセージを送信し、応答を取得します
openclaw_status	OpenClaw ゲートウェイの状態を確認します
openclaw_instances	設定済みの OpenClaw インスタンスをすべて一覧表示します

非同期ツール（長時間実行する操作向け）

ツール	説明
openclaw_chat_async	メッセージをキューに登録し、すぐに task_id を取得します
openclaw_task_status	タスクの進行状況を確認し、結果を取得します
openclaw_task_list	フィルタリングして自分のタスクを一覧表示します
openclaw_task_cancel	保留中のタスクをキャンセルします

タスクは、作成した MCP 接続のスコープに限定されます。HTTP モードでは、1 つのプロセスが多数のクライアントにサービスを提供しますが、クライアントが確認およびキャンセルできるのは自分のタスクだけです。他のクライアントの task_id は、値を知っていても「見つかりません」と表示されます。再接続すると新しいスコープが開始されるため、タスクをキューに登録した接続でポーリングしてください。

マルチインスタンスモード

1 つの MCP サーバーから複数の OpenClaw ゲートウェイをオーケストレーションします。ブリッジは 1 つ、クロウは多数。リクエストを prod、staging、dev、または好きな名前のインスタンスにルーティングできます（lobster-supreme や the-claw-abides も問題なく使える名前です）。

┌──────────────────────────────────────────────────────────────────────┐
│                        Claude.ai / Claude Desktop                    │
│                              (MCP Client)                            │
└──────────────────────┬───────────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────────────┐
│                     OpenClaw MCP Bridge Server                        │
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │  Instance     │  │  Instance     │  │  Instance     │              │
│  │  Registry     │  │  Resolver     │  │  Validator    │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                  │                        │
│  ┌──────┴─────────────────┴──────────────────┴───────┐               │
│  │              Per-Instance OpenClaw Clients          │              │
│  │     (separate auth, timeout, URL per instance)     │              │
│  └────────┬──────────────┬──────────────┬────────────┘               │
└───────────┼──────────────┼──────────────┼────────────────────────────┘
            │              │              │
            ▼              ▼              ▼
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │  🦞 prod     │ │  🦞 staging  │ │  🦞 dev      │
   │  (default)   │ │              │ │              │
   │  :18789      │ │  :18789      │ │  :18789      │
   │  OpenClaw GW │ │  OpenClaw GW │ │  OpenClaw GW │
   └──────────────┘ └──────────────┘ └──────────────┘

セットアップ

OPENCLAW_INSTANCES='[
  {"name": "prod", "url": "http://prod:18789", "token": "tok1", "default": true},
  {"name": "staging", "url": "http://staging:18789", "token": "tok2"},
  {"name": "dev", "url": "http://dev:18789", "token": "tok3"}
]'

使い方

すべてのツールは、特定のゲートウェイを指定するための省略可能な instance パラメーターを受け付けます。

# Chat with staging instance
openclaw_chat message="Deploy status?" instance="staging"

# Check health of prod
openclaw_status instance="prod"

# List all configured instances
openclaw_instances

# Async task targeting dev
openclaw_chat_async message="Run tests" instance="dev"

instance を省略すると、デフォルトのインスタンスが使用されます。各インスタンスは独自の認証トークン、タイムアウト、URL を持ち、完全に分離されています。

主な機能

• 移行不要のアップグレード — 既存の単一インスタンス構成は、設定を変更せずに動作します
• インスタンスごとの分離 — 認証トークン、タイムアウト、URL を個別に設定できます
• 動的ルーティング — Claude がリクエストごとに適切なインスタンスを選択します
• タスク追跡 — 非同期タスクは対象のインスタンスを記憶します
• セキュリティ — トークンは openclaw_instances を通じて公開されません

詳細については、Configuration — Multi-Instance Mode を参照してください。

ドキュメント

• インストール — Claude Desktop と Claude.ai のセットアップ
• 設定 — 環境変数とオプション
• デプロイ — Docker と本番環境のセットアップ
• 脅威モデル — Claude が実行できること／できないこと、信頼境界と攻撃対象領域
• ロギング — ログに記録される内容と場所、および記録されない内容
• 開発 — 貢献とツールの追加
• セキュリティ — セキュリティポリシーとベストプラクティス

セキュリティ

⚠️ 本番環境では必ず認証を有効にしてください！

# Generate secure client secret
export MCP_CLIENT_SECRET=$(openssl rand -hex 32)

# Run with auth enabled
MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \
  openclaw-mcp --transport http

CORS は、明示的に有効にしない限り無効です。ブラウザクライアントからサーバーに直接アクセスする必要がある場合にのみ、CORS_ORIGINS を設定してください。

CORS_ORIGINS=https://claude.ai,https://your-app.com

すべてのセキュリティオプションについては、Configuration を参照してください。

1.8.0 へのアップグレード

HTTP トランスポートでは OAuth が必須になりました。 1.8.0 より前の HTTP モードは、AUTH_ENABLED=true が設定されていない場合、認証なしで動作していたため、イメージを docker run で起動すると、ポートにアクセスできる誰もがすべてのツールを利用できる状態でした。現在は次のようになっています。

• MCP_CLIENT_ID と MCP_CLIENT_SECRET がない場合、サーバーは起動を拒否します。 AUTH_ENABLED=true も引き続き使えますが、設定する必要はなくなりました。
• AUTH_ENABLED=false / --no-auth を指定すると、認証を黙って無効にするのではなく、起動を拒否します。認証なしのサーバーがどうしても必要な場合（例：前段のプロキシですでにすべてのリクエストを認証している場合）は、MCP_DANGEROUSLY_DISABLE_AUTH=true（--dangerously-disable-auth）を設定してください。
• stdio に変更はありません。

非同期タスクは MCP 接続ではなく、OAuth クライアントに紐づくようになりました。 ツール呼び出しの間に新しい MCP セッションを開始するクライアントでも、自身が作成したタスクをポーリングできます（#44）。このブリッジは単一テナントです。クライアントシークレットを持つ人は、すでに同じ OpenClaw ゲートウェイへの完全なアクセス権を持っているため、OAuth クライアントが分離の境界となります。動的に登録されたクライアントには、それぞれ独自の名前空間が割り当てられます。認証がない場合、タスクは引き続き接続ごとにスコープされます。

新しい ALLOWED_HOSTS は、パブリックな Host ヘッダーを保持するリバースプロキシ（Tailscale Serve、proxy_set_header Host $host を設定した nginx）の背後でループバックアドレスにバインドする場合に使用します。これまでは 403 Invalid Host で失敗していました（#41）。設定を参照してください。

1.7.0 へのアップグレード

セキュリティ上の理由から、2 つのデフォルト値が変更されました。どちらも HTTP モードにのみ影響し、stdio に変更はありません。

• CORS はデフォルトで無効になりました。 以前は CORS_ORIGINS が未設定の場合、Access-Control-Allow-Origin: * が送信されていました。ブラウザクライアントでこれが必要な場合は、オリジンを明示的に設定するか（CORS_ORIGINS=https://your-app.com）、以前の動作に戻すには CORS_ORIGINS=* を設定してください。
• 非同期タスクは、作成した接続のスコープに限定されます。 別の接続がキューに追加した task_id を以前はポーリングできていたクライアントも、今後は「not found」を受け取ります。（1.8.0 では、認証済み OAuth クライアントのスコープに変更されます。）

SSE から HTTP トランスポートへの移行

v1.5.0 以降、主要なトランスポートは Streamable HTTP（--transport http）です。従来の SSE トランスポート（--transport sse）は非推奨ですが、後方互換性のため引き続き動作します。

変更点

変更前	変更後
--transport sse	--transport http（推奨）
主なエンドポイント：GET /sse	主なエンドポイント：POST/GET/DELETE /mcp
ヘルス状態："transport": "sse"	ヘルス状態："transport": "streamable-http"

移行手順

1. CLI / Docker：--transport sse を --transport http に置き換えます

   # Before
   openclaw-mcp --transport sse --port 3000
   # After
   openclaw-mcp --transport http --port 3000
   

2. Claude.ai コネクタの URL：変更は不要です。Claude.ai はすでに /mcp（Streamable HTTP）を使用しています。

3. 従来のクライアント：/sse と /messages のエンドポイントは引き続き動作します。SSE 接続のたびに非推奨の警告がログに記録されます。

4. Dockerfile ENTRYPOINT：公式 Docker イメージを使用している場合は、自動的に更新されます。

注： --transport sse は非推奨のエイリアスとして引き続き使用できます。どちらのフラグを指定しても、両方のトランスポートが同時に提供されます。

要件

• Node.js ≥ 20
• HTTP API を有効にして OpenClaw ゲートウェイを実行していること：

  // openclaw.json
  { "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } }
  

ライセンス

MIT

作者

Tomáš Grasl によって作成されました。

関連プロジェクト

• OpenClaw — この MCP が接続する AI アシスタント
• MCP Specification — Model Context Protocol のドキュメント