Skip to content
Back to search

openclaw-mcp

🦞 MCP server for OpenClaw - secure bridge between Claude.ai and your self-hosted OpenClaw assistant with OAuth2 authentication

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/freema--openclaw-mcp/badge.svg)](/listings/freema--openclaw-mcp)

HTML

<a href="/listings/freema--openclaw-mcp"><img src="/api/listings/freema--openclaw-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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:
      - "3000:3000"
    environment:
      - OPENCLAW_URL=http://host.docker.internal:18789
      - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
      - OPENCLAW_AGENT_ID=${OPENCLAW_AGENT_ID:-}
      - OPENCLAW_MODEL=openclaw
      - AUTH_ENABLED=true
      - 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
    security_opt:
      - no-new-privileges

Generate secrets and start:

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)

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

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

> **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](docs/deployment.md#invalid_request--unregistered-redirect_uri-on-authorize)).

See [Installation Guide](docs/installation.md) for details.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json Β· Manifest Β· 23 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "openclaw-mcp",
  4. "description": "Bridge Claude.ai to your self-hosted OpenClaw AI agent via the Model Context Protocol. Chat, manage sessions, and run async tasks.",
  5. "owner": {
  6. "name": "Tomas Grasl"
  7. },
  8. "plugins": [
  9. {
  10. "name": "openclaw",
  11. "source": "./plugins/claude/openclaw",
  12. "description": "OpenClaw AI assistant integration. Chat, manage sessions, access memory, and run async tasks through your OpenClaw instance.",
  13. "version": "0.1.0",
  14. "author": {
  15. "name": "Tomas Grasl"
  16. },
  17. "repository": "https://github.com/freema/openclaw-mcp",
  18. "license": "MIT",
  19. "keywords": ["openclaw", "mcp", "ai-agent", "claude", "orchestration", "async-tasks"],
  20. "category": "integration"
  21. }
  22. ]
  23. }
README.md Β· README Β· 410 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <!-- mcp-name: io.github.freema/openclaw-mcp -->
  2. # OpenClaw MCP Server
  3. [![npm version](https://badge.fury.io/js/openclaw-mcp.svg)](https://www.npmjs.com/package/openclaw-mcp)
  4. [![CI](https://github.com/freema/openclaw-mcp/workflows/CI/badge.svg)](https://github.com/freema/openclaw-mcp/actions/workflows/ci.yml)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  6. [![GHCR](https://img.shields.io/badge/GHCR-ghcr.io%2Ffreema%2Fopenclaw--mcp-blue?logo=github)](https://github.com/freema/openclaw-mcp/pkgs/container/openclaw-mcp)
  7. [![Website](https://img.shields.io/badge/Website-openclaw--mcp.cloud-e24b4a)](https://openclaw-mcp.cloud)
  8. <a href="https://glama.ai/mcp/servers/@freema/openclaw-mcp">
  9. <img width="380" height="200" src="https://glama.ai/mcp/servers/@freema/openclaw-mcp/badge" />
  10. </a>
  11. 🦞 Model Context Protocol (MCP) server for [OpenClaw](https://github.com/openclaw/openclaw) AI assistant integration.
  12. ## Demo
  13. <p align="center">
  14. <img src="docs/assets/claude-ai-demo.gif" alt="OpenClaw MCP in Claude.ai" width="720" />
  15. </p>
  16. ## Why I Built This
  17. 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.
  18. Think of it as an AI assistant orchestrating another AI assistant. Pretty cool, right?
  19. ## Quick Start
  20. ### Docker (Recommended)
  21. Pre-built images are published to GitHub Container Registry on every release.
  22. ```bash
  23. docker pull ghcr.io/freema/openclaw-mcp:latest
  24. ```
  25. Create a `docker-compose.yml`:
  26. ```yaml
  27. services:
  28. mcp-bridge:
  29. image: ghcr.io/freema/openclaw-mcp:latest
  30. container_name: openclaw-mcp
  31. restart: unless-stopped
  32. ports:
  33. - "127.0.0.1:3000:3000" # loopback only, reached through your reverse proxy
  34. environment:
  35. - OPENCLAW_URL=http://host.docker.internal:18789
  36. - OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
  37. - OPENCLAW_AGENT_ID=${OPENCLAW_AGENT_ID:-}
  38. - OPENCLAW_MODEL=openclaw
  39. - MCP_CLIENT_ID=openclaw
  40. - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
  41. - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
  42. - MCP_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
  43. - TRUST_PROXY=1
  44. - CORS_ORIGINS=https://claude.ai
  45. extra_hosts:
  46. - "host.docker.internal:host-gateway"
  47. read_only: true
  48. cap_drop:
  49. - ALL
  50. security_opt:
  51. - no-new-privileges
  52. ```
  53. The port is published on `127.0.0.1` only: the bridge speaks plain HTTP and is
  54. meant to sit behind a TLS-terminating reverse proxy on the same host (see
  55. [Deployment](docs/deployment.md#reverse-proxy-https)).
  56. Generate secrets and start:
  57. ```bash
  58. export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
  59. export OPENCLAW_GATEWAY_TOKEN=your-gateway-token
  60. docker compose up -d
  61. ```
  62. 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`.
  63. > **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.
  64. > **Tip:** Pin a specific version instead of `latest` for production: `ghcr.io/freema/openclaw-mcp:1.8.1`
  65. > **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](#security).
  66. ### Local (Claude Desktop)
  67. ```bash
  68. npx openclaw-mcp
  69. ```
  70. Add to your Claude Desktop config:
  71. ```json
  72. {
  73. "mcpServers": {
  74. "openclaw": {
  75. "command": "npx",
  76. "args": ["openclaw-mcp"],
  77. "env": {
  78. "OPENCLAW_URL": "http://127.0.0.1:18789",
  79. "OPENCLAW_GATEWAY_TOKEN": "your-gateway-token",
  80. "OPENCLAW_AGENT_ID": "main",
  81. "OPENCLAW_MODEL": "openclaw",
  82. "OPENCLAW_TIMEOUT_MS": "300000"
  83. }
  84. }
  85. }
  86. }
  87. ```
  88. ### Remote (Claude.ai) without Docker
  89. ```bash
  90. MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=your-secret \
  91. MCP_ISSUER_URL=https://mcp.your-domain.com \
  92. CORS_ORIGINS=https://claude.ai OPENCLAW_GATEWAY_TOKEN=your-gateway-token \
  93. npx openclaw-mcp --transport http --port 3000
  94. ```
  95. > **Important:** When running behind a reverse proxy (Caddy, nginx, Traefik, Cloudflare Tunnel, etc.) you **must** set:
  96. > - `MCP_ISSUER_URL` (or `--issuer-url`) to your public HTTPS URL β€” otherwise OAuth metadata advertises `http://localhost:3000` and clients fail to authenticate.
  97. > - `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`.
  98. > **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](docs/deployment.md#invalid_request--unregistered-redirect_uri-on-authorize)).
  99. See [Installation Guide](docs/installation.md) for details.
  100. ## Architecture
  101. ```
  102. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  103. β”‚ Your Server β”‚
  104. β”‚ β”‚
  105. β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
  106. β”‚ β”‚ OpenClaw β”‚ β”‚ OpenClaw MCP β”‚ β”‚
  107. β”‚ β”‚ Gateway │◄────►│ Bridge Server β”‚ β”‚
  108. β”‚ β”‚ :18789 β”‚ β”‚ :3000 β”‚ β”‚
  109. β”‚ β”‚ β”‚ β”‚ β”‚ β”‚
  110. β”‚ β”‚ OpenAI-compat β”‚ β”‚ - OAuth 2.1 auth β”‚ β”‚
  111. β”‚ β”‚ /v1/chat/... β”‚ β”‚ - CORS protection β”‚ β”‚
  112. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ - Input validation β”‚ β”‚
  113. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
  114. β”‚ β”‚ β”‚
  115. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  116. β”‚ HTTPS + OAuth 2.1
  117. β–Ό
  118. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  119. β”‚ Claude.ai β”‚
  120. β”‚ (MCP Client) β”‚
  121. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  122. ```
  123. ## Available Tools
  124. ### Sync Tools
  125. | Tool | Description |
  126. |------|-------------|
  127. | `openclaw_chat` | Send messages to OpenClaw and get responses |
  128. | `openclaw_status` | Check OpenClaw gateway health |
  129. | `openclaw_instances` | List all configured OpenClaw instances |
  130. ### Async Tools (for long-running operations)
  131. | Tool | Description |
  132. |------|-------------|
  133. | `openclaw_chat_async` | Queue a message, get task_id immediately |
  134. | `openclaw_task_status` | Check task progress and get results |
  135. | `openclaw_task_list` | List your tasks with filtering |
  136. | `openclaw_task_cancel` | Cancel a pending task |
  137. Tasks belong to whoever created them. In HTTP mode that is the authenticated
  138. OAuth client, so a client can poll its tasks from a new MCP session, and
  139. another client's `task_id` reads as "not found" even if it is known. Without
  140. an authenticated client (stdio) tasks are scoped to the connection.
  141. ## Multi-Instance Mode
  142. 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).
  143. ```
  144. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  145. β”‚ Claude.ai / Claude Desktop β”‚
  146. β”‚ (MCP Client) β”‚
  147. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  148. β”‚
  149. β–Ό
  150. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  151. β”‚ OpenClaw MCP Bridge Server β”‚
  152. β”‚ β”‚
  153. β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚
  154. β”‚ β”‚ Instance β”‚ β”‚ Instance β”‚ β”‚ Instance β”‚ β”‚
  155. β”‚ β”‚ Registry β”‚ β”‚ Resolver β”‚ β”‚ Validator β”‚ β”‚
  156. β”‚ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
  157. β”‚ β”‚ β”‚ β”‚ β”‚
  158. β”‚ β”Œβ”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β” β”‚
  159. β”‚ β”‚ Per-Instance OpenClaw Clients β”‚ β”‚
  160. β”‚ β”‚ (separate auth, timeout, URL per instance) β”‚ β”‚
  161. β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚
  162. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  163. β”‚ β”‚ β”‚
  164. β–Ό β–Ό β–Ό
  165. β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  166. β”‚ 🦞 prod β”‚ β”‚ 🦞 staging β”‚ β”‚ 🦞 dev β”‚
  167. β”‚ (default) β”‚ β”‚ β”‚ β”‚ β”‚
  168. β”‚ :18789 β”‚ β”‚ :18789 β”‚ β”‚ :18789 β”‚
  169. β”‚ OpenClaw GW β”‚ β”‚ OpenClaw GW β”‚ β”‚ OpenClaw GW β”‚
  170. β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
  171. ```
  172. ### Setup
  173. ```bash
  174. OPENCLAW_INSTANCES='[
  175. {"name": "prod", "url": "http://prod:18789", "token": "tok1", "default": true},
  176. {"name": "staging", "url": "http://staging:18789", "token": "tok2"},
  177. {"name": "dev", "url": "http://dev:18789", "token": "tok3"}
  178. ]'
  179. ```
  180. ### Usage
  181. All tools accept an optional `instance` parameter to target a specific gateway:
  182. ```
  183. # Chat with staging instance
  184. openclaw_chat message="Deploy status?" instance="staging"
  185. # Check health of prod
  186. openclaw_status instance="prod"
  187. # List all configured instances
  188. openclaw_instances
  189. # Async task targeting dev
  190. openclaw_chat_async message="Run tests" instance="dev"
  191. ```
  192. When `instance` is omitted, the default instance is used. Each instance has its own auth token, timeout, and URL β€” fully isolated.
  193. ### Key Features
  194. - **Zero-migration upgrade** β€” existing single-instance deployments work without any config change
  195. - **Per-instance isolation** β€” separate auth tokens, timeouts, and URLs
  196. - **Dynamic routing** β€” Claude picks the right instance per request
  197. - **Task tracking** β€” async tasks remember which instance they target
  198. - **Security** β€” tokens are never exposed via `openclaw_instances`
  199. See [Configuration β€” Multi-Instance Mode](docs/configuration.md#multi-instance-mode) for the full reference.
  200. ## Documentation
  201. - [Installation](docs/installation.md) β€” Setup for Claude Desktop & Claude.ai
  202. - [Configuration](docs/configuration.md) β€” Environment variables & options
  203. - [Deployment](docs/deployment.md) β€” Docker & production setup
  204. - [Threat Model](docs/threat-model.md) β€” What Claude can/can't trigger, trust boundaries & attack surfaces
  205. - [Logging](docs/logging.md) β€” What gets logged, where, and what is never logged
  206. - [Development](docs/development.md) β€” Contributing & adding tools
  207. - [Security](SECURITY.md) β€” Security policy & best practices
  208. ## Security
  209. ⚠️ **Always enable authentication in production!**
  210. ```bash
  211. # Generate secure client secret
  212. export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
  213. # Run with auth enabled
  214. MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \
  215. openclaw-mcp --transport http
  216. ```
  217. CORS is disabled unless you opt in. Set `CORS_ORIGINS` only when a browser
  218. client needs to reach the server directly:
  219. ```bash
  220. CORS_ORIGINS=https://claude.ai,https://your-app.com
  221. ```
  222. See [Configuration](docs/configuration.md) for all security options.
  223. ### Give the bridge a least-privilege agent
  224. The bridge passes text to an OpenClaw agent and cannot judge what that text
  225. makes the agent do. Anything Claude reads β€” a web page, an email, a document β€”
  226. can end up in an `openclaw_chat` call, so prompt injection into an agent that
  227. can run shell commands is the biggest real-world risk of this setup, and OAuth
  228. does not help against it. Do not point the bridge at your main agent: create a
  229. dedicated OpenClaw agent with only the tools it needs, sandboxed, and select it
  230. with `OPENCLAW_AGENT_ID`. Details in [SECURITY.md](SECURITY.md#prompt-injection-and-the-openclaw-agent)
  231. and the [Threat Model](docs/threat-model.md).
  232. ### Upgrading to 1.8.1
  233. A security and maintenance release; no configuration changes are required.
  234. - **`docker-compose.yml` now publishes the port on `127.0.0.1` only.** If you
  235. use the compose file from this repository and reach port 3000 directly from
  236. another machine (no reverse proxy on the same host), it stops being
  237. reachable after you update the file. Put a reverse proxy in front, or set
  238. `BIND_ADDRESS=0.0.0.0` to restore the old binding. A compose file you
  239. maintain yourself, and `docker run`, are not affected. The compose file also
  240. drops all Linux capabilities (`cap_drop: [ALL]`).
  241. - **MCP SDK 1.32.2** with its security fixes; the Docker image runs on
  242. Node.js 24. The npm package still supports Node.js β‰₯ 20.
  243. - **Request bodies** on `/mcp` and `/messages` are limited to 4 MiB and parsed
  244. only after authentication. Long non-ASCII messages that used to fail with
  245. `413` under the old implicit 100 kB limit now work; JSON-RPC batches are
  246. capped at 100 messages by the SDK.
  247. See the [changelog](CHANGELOG.md) for the full list.
  248. ### Upgrading to 1.8.0
  249. **OAuth is now mandatory for the HTTP transport.** Before 1.8.0 HTTP mode ran
  250. without authentication unless `AUTH_ENABLED=true` was set, so a bare
  251. `docker run` of the image exposed every tool to anyone who could reach the
  252. port. Now:
  253. - Without `MCP_CLIENT_ID` and `MCP_CLIENT_SECRET` the server refuses to start.
  254. `AUTH_ENABLED=true` still works but is no longer needed.
  255. - `AUTH_ENABLED=false` / `--no-auth` refuses to start instead of silently
  256. disabling auth. If you really need an unauthenticated server (e.g. a proxy
  257. in front already authenticates every request), set
  258. `MCP_DANGEROUSLY_DISABLE_AUTH=true` (`--dangerously-disable-auth`).
  259. - stdio is unchanged.
  260. **Async tasks now belong to the OAuth client, not the MCP connection.** A
  261. client that opens a new MCP session between tool calls can poll the tasks it
  262. created ([#44](https://github.com/freema/openclaw-mcp/issues/44)). The bridge
  263. is single-tenant β€” whoever holds the client secret already has full access to
  264. the same OpenClaw gateway β€” so the OAuth client is the isolation boundary.
  265. Dynamically registered clients each get their own namespace. Without auth,
  266. tasks stay scoped to the connection.
  267. **New `ALLOWED_HOSTS`** for a loopback bind behind a reverse proxy that
  268. preserves the public `Host` header (Tailscale Serve, nginx with
  269. `proxy_set_header Host $host`), which previously failed with `403 Invalid Host`
  270. ([#41](https://github.com/freema/openclaw-mcp/issues/41)). See
  271. [configuration](docs/configuration.md#server-settings-http-transport).
  272. ### Upgrading to 1.7.0
  273. Two defaults changed for security. Both only affect HTTP mode; stdio is
  274. unchanged.
  275. - **CORS is now off by default.** Previously an unset `CORS_ORIGINS` sent
  276. `Access-Control-Allow-Origin: *`. If a browser client depends on that, set
  277. the origins explicitly (`CORS_ORIGINS=https://your-app.com`), or
  278. `CORS_ORIGINS=*` to restore the old behaviour.
  279. - **Async tasks are scoped to the connection that created them.** A client
  280. that used to poll a `task_id` queued by a different connection will now get
  281. "not found". (1.8.0 relaxes this to the authenticated OAuth client.)
  282. ## Migrating from SSE to HTTP transport
  283. 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.
  284. ### What changed
  285. | Before | After |
  286. |--------|-------|
  287. | `--transport sse` | `--transport http` (recommended) |
  288. | Primary endpoint: `GET /sse` | Primary endpoint: `POST/GET/DELETE /mcp` |
  289. | Health: `"transport": "sse"` | Health: `"transport": "streamable-http"` |
  290. ### Migration steps
  291. 1. **CLI / Docker**: Replace `--transport sse` with `--transport http`
  292. ```bash
  293. # Before
  294. openclaw-mcp --transport sse --port 3000
  295. # After
  296. openclaw-mcp --transport http --port 3000
  297. ```
  298. 2. **Claude.ai connector URL**: No change needed β€” Claude.ai already uses `/mcp` (Streamable HTTP)
  299. 3. **Legacy clients**: The `/sse` and `/messages` endpoints still work. A deprecation warning is logged on each SSE connection.
  300. 4. **Dockerfile ENTRYPOINT**: Updated automatically if using the official Docker image
  301. > **Note:** `--transport sse` will continue to work as a deprecated alias. Both transports are served simultaneously regardless of which flag you use.
  302. ## Requirements
  303. - Node.js β‰₯ 20
  304. - OpenClaw gateway running with HTTP API enabled:
  305. ```json5
  306. // openclaw.json
  307. { "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } }
  308. ```
  309. ## License
  310. MIT
  311. ## Author
  312. Created by [TomΓ‘Ε‘ Grasl](https://www.tomasgrasl.cz/)
  313. ## Related Projects
  314. - [OpenClaw](https://github.com/openclaw/openclaw) β€” The AI assistant this MCP connects to
  315. - [MCP Specification](https://spec.modelcontextprotocol.io/) β€” Model Context Protocol docs

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.