openclaw-mcp
You can use this MCP server to bridge MCP clients to one or more OpenClaw gateways for chat, health checks, and async task management.
Send synchronous messages to OpenClaw with
openclaw_chat, optionally using a target instance and session ID.Check gateway status and health with
openclaw_status.List configured OpenClaw instances with
openclaw_instances.Queue long-running chat requests with
openclaw_chat_async, including optional priority and session ID.Poll async task status and retrieve results with
openclaw_task_status.List or filter tasks by status, instance, or session with
openclaw_task_list.Cancel pending tasks with
openclaw_task_cancel.Route requests across multiple isolated OpenClaw gateways by passing an
instancename.
OpenClaw MCP Server
π¦ Model Context Protocol (MCP) server for OpenClaw AI assistant integration.
Demo
Related MCP server: OpenClaw MCP Server
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:latestCreate 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-privilegesThe 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-token
docker compose up -dThen 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
latestfor production:ghcr.io/freema/openclaw-mcp:1.8.1
Use a least-privilege agent. Set
OPENCLAW_AGENT_IDto 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-mcpAdd 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 3000Important: 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 advertiseshttp://localhost:3000and clients fail to authenticate.
TRUST_PROXY=1(or--trust-proxy 1) β otherwiseexpress-rate-limitrejects the proxy'sX-Forwarded-Forheader and/tokencrashes withERR_ERL_UNEXPECTED_X_FORWARDED_FOR.
Recommended: Set
MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callbackso authorization codes can only be delivered to Claude's callbacks. Note the exact/api/mcp/auth_callbackpath β matching is exact, and getting it wrong fails OAuth withUnregistered 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
Tool | Description |
| Send messages to OpenClaw and get responses |
| Check OpenClaw gateway health |
| List all configured OpenClaw instances |
Async Tools (for long-running operations)
Tool | Description |
| Queue a message, get task_id immediately |
| Check task progress and get results |
| List your tasks with filtering |
| Cancel a pending task |
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 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"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 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 httpCORS 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.comSee 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.ymlnow publishes the port on127.0.0.1only. 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 setBIND_ADDRESS=0.0.0.0to restore the old binding. A compose file you maintain yourself, anddocker 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
/mcpand/messagesare limited to 4 MiB and parsed only after authentication. Long non-ASCII messages that used to fail with413under 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_IDandMCP_CLIENT_SECRETthe server refuses to start.AUTH_ENABLED=truestill works but is no longer needed.AUTH_ENABLED=false/--no-authrefuses to start instead of silently disabling auth. If you really need an unauthenticated server (e.g. a proxy in front already authenticates every request), setMCP_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_ORIGINSsentAccess-Control-Allow-Origin: *. If a browser client depends on that, set the origins explicitly (CORS_ORIGINS=https://your-app.com), orCORS_ORIGINS=*to restore the old behaviour.Async tasks are scoped to the connection that created them. A client that used to poll a
task_idqueued 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
Before | After |
|
|
Primary endpoint: | Primary endpoint: |
Health: | Health: |
Migration steps
CLI / Docker: Replace
--transport ssewith--transport http# Before openclaw-mcp --transport sse --port 3000 # After openclaw-mcp --transport http --port 3000Claude.ai connector URL: No change needed β Claude.ai already uses
/mcp(Streamable HTTP)Legacy clients: The
/sseand/messagesendpoints still work. A deprecation warning is logged on each SSE connection.Dockerfile ENTRYPOINT: Updated automatically if using the official Docker image
Note:
--transport ssewill 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:
// 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
Available Tools
7 toolsopenclaw_chatC
Send a message to OpenClaw and get a response
Inputs: message (required), instance, session_id.
openclaw_chat_asyncA
Send a message to OpenClaw asynchronously. Returns a task_id immediately that can be polled for results. Use this for potentially long-running conversations.
Inputs: message (required), instance, priority, session_id.
openclaw_instancesA
List all configured OpenClaw instances. Shows instance names, URLs, and which is the default. Use instance names in other tools to target a specific OpenClaw gateway.
Inputs: no named parameters.
openclaw_statusB
Get OpenClaw gateway status and health information
Inputs: instance.
openclaw_task_cancelA
Cancel a pending task. Only works for tasks that haven't started yet.
Inputs: task_id (required).
openclaw_task_listA
List all tasks. Optionally filter by status, session, or instance.
Inputs: status, instance, session_id.
openclaw_task_statusB
Check the status of an async task. Returns status, and result if completed.
Inputs: task_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 7 tools
Most tools have distinct purposes, but openclaw_chat and openclaw_chat_async could be confused if an agent skims descriptions. The async variant is clearly labeled, so overall disambiguation is good but not perfect.
All tools use the consistent pattern 'openclaw_verb_noun' with snake_case. This makes it easy to predict tool names and understand their function.
Seven tools is ideal for an API gateway wrapper. Each tool covers a distinct operation without redundancy, and the scope is well-scoped for interacting with OpenClaw instances.
The set covers core operations: chat (sync/async), instance management, health status, and task management. Minor gap: no tool for listing sessions or conversation history, but the core workflows are complete.
Maintenance
Related MCP Connectors
MCP server for Argo RPG Platform β connects AI assistants to campaign data via OAuth2
BeautySpark MCP server for ChatGPT, Claude and other MCP clients
Talk to your public-facing AI from any MCP client β Claude, ChatGPT, Cursor, Cline, Windsurf.
Free MCP server for WordPress: Claude and ChatGPT connect with OAuth. No account, cap or API key.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables any AI agent to call Claude using your existing Max/Pro subscription via OAuth, avoiding additional API billing.11MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables Claude.ai and Claude Desktop to securely connect to self-hosted OpenClaw assistants through OAuth2-authenticated MCP, supporting chat, health checks, multi-instance routing, and asynchronous task management.406 npmMIT
- AlicenseNot gradedqualityAmaintenanceBridges Claude.ai and Claude Desktop to self-hosted OpenClaw AI assistants through an OAuth 2.1-secured HTTP endpoint. Enables sending chat messages, tracking long-running tasks, checking gateway health, and routing requests across multiple isolated instances from a single connection.406 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables secure OAuth 2.1 access from Claude.ai and Claude Desktop to self-hosted OpenClaw assistants, including chat, health checks, async task management, and multi-instance routing.406 npmMIT