OpenClaw MCP Server

OpenClaw MCP Server

[npm version] [CI] [License: MIT] [GHCR] [Website]

🦞 Model Context Protocol (MCP) server for OpenClaw AI assistant integration.

Demo

[OpenClaw MCP in Claude.ai]

Why I Built This

Hey! I created this MCP server because I didn't want to rely solely on messaging channels to communicate with OpenClaw. What really excites me is the ability to connect OpenClaw to the Claude web UI. Essentially, my chat can delegate tasks to my Claw bot, which then handles everything else — like spinning up Claude Code to fix issues for me.

Think of it as an AI assistant orchestrating another AI assistant. Pretty cool, right?

Quick Start

Docker (Recommended)

Pre-built images are published to GitHub Container Registry on every release.

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

Create a docker-compose.yml:

services:  mcp-bridge:    image: ghcr.io/freema/openclaw-mcp:latest    container_name: openclaw-mcp    restart: unless-stopped    ports:      - "127.0.0.1:3000:3000"   # loopback only, reached through your reverse proxy    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    cap_drop:      - ALL    security_opt:      - no-new-privileges

The port is published on 127.0.0.1 only: the bridge speaks plain HTTP and is meant to sit behind a TLS-terminating reverse proxy on the same host (see Deployment).

Generate secrets and start:

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

Then in Claude.ai add a custom MCP connector pointing to https://your-domain.com/mcp with MCP_CLIENT_ID=openclaw and your MCP_CLIENT_SECRET.

Important: The connector URL must end with /mcp — that's the Streamable HTTP endpoint. A bare domain (https://your-domain.com) hits the server root and returns 404 after OAuth completes.

Tip: Pin a specific version instead of latest for production: ghcr.io/freema/openclaw-mcp:1.8.1

Use a least-privilege agent. Set OPENCLAW_AGENT_ID to a dedicated OpenClaw agent that only has the tools you want Claude to reach — not your main agent with shell access. See Security.

Local (Claude Desktop)

npx openclaw-mcp

Add to your Claude Desktop config:

{  "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"      }    }  }}

Remote (Claude.ai) without Docker

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

Important: When running behind a reverse proxy (Caddy, nginx, Traefik, Cloudflare Tunnel, etc.) you must set:

• MCP_ISSUER_URL (or --issuer-url) to your public HTTPS URL — otherwise OAuth metadata advertises http://localhost:3000 and clients fail to authenticate.
• TRUST_PROXY=1 (or --trust-proxy 1) — otherwise express-rate-limit rejects the proxy's X-Forwarded-For header and /token crashes with ERR_ERL_UNEXPECTED_X_FORWARDED_FOR.

Recommended: Set MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback so authorization codes can only be delivered to Claude's callbacks. Note the exact /api/mcp/auth_callback path — matching is exact, and getting it wrong fails OAuth with Unregistered redirect_uri (see Troubleshooting).

See Installation Guide for details.

Architecture

┌─────────────────────────────────────────────────────────────────┐│                         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)  │                              └─────────────────┘

Available Tools

Sync Tools

Async Tools (for long-running operations)

Tasks belong to whoever created them. In HTTP mode that is the authenticated OAuth client, so a client can poll its tasks from a new MCP session, and another client's task_id reads as "not found" even if it is known. Without an authenticated client (stdio) tasks are scoped to the connection.

Multi-Instance Mode

Orchestrate multiple OpenClaw gateways from a single MCP server. One bridge, many claws — route requests to prod, staging, dev, or whatever you name them (lobster-supreme and the-claw-abides are perfectly valid names).

┌──────────────────────────────────────────────────────────────────────┐│                        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 │   └──────────────┘ └──────────────┘ └──────────────┘

Setup

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"}]'

Usage

All tools accept an optional instance parameter to target a specific gateway:

# Chat with staging instanceopenclaw_chat message="Deploy status?" instance="staging"
# Check health of prodopenclaw_status instance="prod"
# List all configured instancesopenclaw_instances
# Async task targeting devopenclaw_chat_async message="Run tests" instance="dev"

When instance is omitted, the default instance is used. Each instance has its own auth token, timeout, and URL — fully isolated.

Key Features

• Zero-migration upgrade — existing single-instance deployments work without any config change
• Per-instance isolation — separate auth tokens, timeouts, and URLs
• Dynamic routing — Claude picks the right instance per request
• Task tracking — async tasks remember which instance they target
• Security — tokens are never exposed via openclaw_instances

See Configuration — Multi-Instance Mode for the full reference.

Documentation

• Installation — Setup for Claude Desktop & Claude.ai
• Configuration — Environment variables & options
• Deployment — Docker & production setup
• Threat Model — What Claude can/can't trigger, trust boundaries & attack surfaces
• Logging — What gets logged, where, and what is never logged
• Development — Contributing & adding tools
• Security — Security policy & best practices

Security

⚠️ Always enable authentication in production!

# Generate secure client secretexport MCP_CLIENT_SECRET=$(openssl rand -hex 32)
# Run with auth enabledMCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \  openclaw-mcp --transport http

CORS is disabled unless you opt in. Set CORS_ORIGINS only when a browser client needs to reach the server directly:

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

See Configuration for all security options.

Give the bridge a least-privilege agent

The bridge passes text to an OpenClaw agent and cannot judge what that text makes the agent do. Anything Claude reads — a web page, an email, a document — can end up in an openclaw_chat call, so prompt injection into an agent that can run shell commands is the biggest real-world risk of this setup, and OAuth does not help against it. Do not point the bridge at your main agent: create a dedicated OpenClaw agent with only the tools it needs, sandboxed, and select it with OPENCLAW_AGENT_ID. Details in SECURITY.md and the Threat Model.

Upgrading to 1.8.1

A security and maintenance release; no configuration changes are required.

• docker-compose.yml now publishes the port on 127.0.0.1 only. If you use the compose file from this repository and reach port 3000 directly from another machine (no reverse proxy on the same host), it stops being reachable after you update the file. Put a reverse proxy in front, or set BIND_ADDRESS=0.0.0.0 to restore the old binding. A compose file you maintain yourself, and docker run, are not affected. The compose file also drops all Linux capabilities (cap_drop: [ALL]).
• MCP SDK 1.32.2 with its security fixes; the Docker image runs on Node.js 24. The npm package still supports Node.js ≥ 20.
• Request bodies on /mcp and /messages are limited to 4 MiB and parsed only after authentication. Long non-ASCII messages that used to fail with 413 under the old implicit 100 kB limit now work; JSON-RPC batches are capped at 100 messages by the SDK.

See the changelog for the full list.

Upgrading to 1.8.0

OAuth is now mandatory for the HTTP transport. Before 1.8.0 HTTP mode ran without authentication unless AUTH_ENABLED=true was set, so a bare docker run of the image exposed every tool to anyone who could reach the port. Now:

• Without MCP_CLIENT_ID and MCP_CLIENT_SECRET the server refuses to start. AUTH_ENABLED=true still works but is no longer needed.
• AUTH_ENABLED=false / --no-auth refuses to start instead of silently disabling auth. If you really need an unauthenticated server (e.g. a proxy in front already authenticates every request), set MCP_DANGEROUSLY_DISABLE_AUTH=true (--dangerously-disable-auth).
• stdio is unchanged.

Async tasks now belong to the OAuth client, not the MCP connection. A client that opens a new MCP session between tool calls can poll the tasks it created (#44). The bridge is single-tenant — whoever holds the client secret already has full access to the same OpenClaw gateway — so the OAuth client is the isolation boundary. Dynamically registered clients each get their own namespace. Without auth, tasks stay scoped to the connection.

New ALLOWED_HOSTS for a loopback bind behind a reverse proxy that preserves the public Host header (Tailscale Serve, nginx with proxy_set_header Host $host), which previously failed with 403 Invalid Host (#41). See configuration.

Upgrading to 1.7.0

Two defaults changed for security. Both only affect HTTP mode; stdio is unchanged.

• CORS is now off by default. Previously an unset CORS_ORIGINS sent Access-Control-Allow-Origin: *. If a browser client depends on that, set the origins explicitly (CORS_ORIGINS=https://your-app.com), or CORS_ORIGINS=* to restore the old behaviour.
• Async tasks are scoped to the connection that created them. A client that used to poll a task_id queued by a different connection will now get "not found". (1.8.0 relaxes this to the authenticated OAuth client.)

Migrating from SSE to HTTP transport

Starting with v1.5.0, the primary transport is Streamable HTTP (--transport http). The legacy SSE transport (--transport sse) is deprecated but still works for backward compatibility.

What changed

Migration steps

1. CLI / Docker: Replace --transport sse with --transport http

   bash

   # Beforeopenclaw-mcp --transport sse --port 3000# Afteropenclaw-mcp --transport http --port 3000

2. Claude.ai connector URL: No change needed — Claude.ai already uses /mcp (Streamable HTTP)

3. Legacy clients: The /sse and /messages endpoints still work. A deprecation warning is logged on each SSE connection.

4. Dockerfile ENTRYPOINT: Updated automatically if using the official Docker image

Note: --transport sse will continue to work as a deprecated alias. Both transports are served simultaneously regardless of which flag you use.

Requirements

• Node.js ≥ 20
• OpenClaw gateway running with HTTP API enabled:
  json5

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

License

MIT

Author

Created by Tomáš Grasl

Related Projects

• OpenClaw — The AI assistant this MCP connects to
• MCP Specification — Model Context Protocol docs