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.
Create a docker-compose.yml:
Generate secrets and start:
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)
Add to your Claude Desktop config:
Remote (Claude.ai) without Docker
> **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
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 your tasks with filtering |
| openclaw_task_cancel | Cancel a pending task |
Tasks are scoped to the MCP connection that created them. In HTTP mode, where
one process serves many clients, a client can only see and cancel its own
tasks — another client's task_id reads as "not found" even if it is known.
Reconnecting starts a fresh scope, so poll a task on the connection that
queued it.
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).
Setup
Usage
All tools accept an optional instance parameter to target a specific gateway: