MCP server bridging Claude.ai/Desktop with self-hosted OpenClaw via OAuth 2.1.
io.github.freema/openclaw-mcp MCP Server
This MCP server bridges Claude.ai/Desktop with a self-hosted OpenClaw service using OAuth 2.1. It is delivered as the io.github.freema/openclaw-mcp package and is associated with container distribution at ghcr.io/freema/openclaw--mcp.
π¦ Model Context Protocol (MCP) server for OpenClaw AI assistant integration.
Demo
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.
bash
docker pull ghcr.io/freema/openclaw-mcp:latest
Create a docker-compose.yml:
yaml
services:mcp-bridge:image:ghcr.io/freema/openclaw-mcp:latestcontainer_name:openclaw-mcprestart:unless-stoppedports:-"127.0.0.1:3000:3000"# loopback only, reached through your reverse proxyenvironment:-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.aiextra_hosts:-"host.docker.internal:host-gateway"read_only:truecap_drop:-ALLsecurity_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).
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.
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).
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).
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.
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
Before
After
--transport sse
--transport http (recommended)
Primary endpoint: GET /sse
Primary endpoint: POST/GET/DELETE /mcp
Health: "transport": "sse"
Health: "transport": "streamable-http"
Migration steps
CLI / Docker: Replace --transport sse with --transport http
bash
# Before
openclaw-mcp --transport sse --port 3000
# After
openclaw-mcp --transport http --port 3000