io.github.freema/openclaw-mcp

Official

by freema · TypeScript

OpenClaw MCP Server

MCP server bridging Claude.ai/Desktop with self-hosted OpenClaw via OAuth 2.1.

Bridge Claude.ai/Desktop to self-hosted OpenClaw via OAuth 2.1.

Topics

mcp-serveropen-clawproductivitydocker-composesecuritytypescript

README.md14 KBView on GitHub

OpenClaw MCP Server

🦞 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: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_MODEL=openclaw
      - AUTH_ENABLED=true
      - MCP_CLIENT_ID=openclaw
      - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
      - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
      - TRUST_PROXY=1
      - CORS_ORIGINS=https://claude.ai
    extra_hosts:
      - "host.docker.internal:host-gateway"
    read_only: true
    security_opt:
      - no-new-privileges

Generate secrets and start:

bash

export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
export OPENCLAW_GATEWAY_TOKEN=your-gateway-token
docker 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.1.0

Local (Claude Desktop)

bash

npx openclaw-mcp

Add to your Claude Desktop config:

json

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

Remote (Claude.ai) without Docker

bash

AUTH_ENABLED=true 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.

See Installation Guide for details.

Architecture

code

┌─────────────────────────────────────────────────────────────────┐
│                         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
`openclaw_chat`	Send messages to OpenClaw and get responses
`openclaw_status`	Check OpenClaw gateway health
`openclaw_instances`	List all configured OpenClaw instances

Async Tools (for long-running operations)

Tool	Description
`openclaw_chat_async`	Queue a message, get task_id immediately
`openclaw_task_status`	Check task progress and get results
`openclaw_task_list`	List all tasks with filtering
`openclaw_task_cancel`	Cancel a pending task

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).

code

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

bash

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:

code

# 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!

bash

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

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

Configure CORS to restrict access:

bash

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

See Configuration for all security options.

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

Claude.ai connector URL: No change needed — Claude.ai already uses /mcp (Streamable HTTP)
Legacy clients: The /sse and /messages endpoints still work. A deprecation warning is logged on each SSE connection.
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

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

Install

Configuration

Environment variables

OPENCLAW_URLrequireddefault http://127.0.0.1:18789

URL of your OpenClaw gateway

OPENCLAW_GATEWAY_TOKENrequiredsecret

Bearer token for OpenClaw gateway authentication

OPENCLAW_MODELdefault openclaw

Model name for chat completions (e.g. 'openclaw' or 'openclaw/<agentId>')

OPENCLAW_TIMEOUT_MSdefault 120000

Request timeout in milliseconds

claude_desktop_config.json

{
  "mcpServers": {
    "openclaw-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "openclaw-mcp@1.6.0"
      ],
      "env": {
        "OPENCLAW_URL": "http://127.0.0.1:18789",
        "OPENCLAW_GATEWAY_TOKEN": "<YOUR_OPENCLAW_GATEWAY_TOKEN>",
        "OPENCLAW_MODEL": "openclaw",
        "OPENCLAW_TIMEOUT_MS": "120000"
      }
    }
  }
}

Topics

OpenClaw MCP Server

Demo

Why I Built This

Quick Start

Docker (Recommended)

Local (Claude Desktop)

Remote (Claude.ai) without Docker

Architecture

Available Tools

Sync Tools

Async Tools (for long-running operations)

Multi-Instance Mode

Setup

Usage

Key Features

Documentation

Security

Migrating from SSE to HTTP transport

What changed

Migration steps

Requirements

License

Author

Related Projects

Install

Configuration