openclaw-mcp 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Tomáš Grasl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -4,8 +4,18 @@
 [![CI](https://github.com/freema/openclaw-mcp/workflows/CI/badge.svg)](https://github.com/freema/openclaw-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
+<a href="https://glama.ai/mcp/servers/@freema/openclaw-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@freema/openclaw-mcp/badge" />
+</a>
+
 🦞 Model Context Protocol (MCP) server for [OpenClaw](https://github.com/openclaw/openclaw) AI assistant integration.
 
+## Demo
+
+<p align="center">
+  <img src="docs/assets/claude-ai-demo.gif" alt="OpenClaw MCP in Claude.ai" width="720" />
+</p>
+
 ## 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.
@@ -41,10 +51,13 @@ Add to your Claude Desktop config:
 
 ```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 sse --port 3000
 ```
 
+> **Important:** When running behind a reverse proxy (Caddy, nginx, etc.), you **must** set `MCP_ISSUER_URL` (or `--issuer-url`) to your public HTTPS URL. Without this, OAuth metadata will advertise `http://localhost:3000` and clients will fail to authenticate.
+
 Then in Claude.ai add a custom connector with your `MCP_CLIENT_ID` and `MCP_CLIENT_SECRET`.
 
 See [Installation Guide](docs/installation.md) for details.
@@ -124,7 +137,11 @@ See [Configuration](docs/configuration.md) for all security options.
 ## Requirements
 
 - Node.js ≥ 20
-- OpenClaw gateway running
+- OpenClaw gateway running with HTTP API enabled:
+  ```json5
+  // openclaw.json
+  { "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } }
+  ```
 
 ## License
 

package/docs/deployment.md

@@ -20,6 +20,8 @@ services:
       - AUTH_ENABLED=${AUTH_ENABLED:-true}
       - MCP_CLIENT_ID=${MCP_CLIENT_ID:-openclaw}
       - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET:-}
+      - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
+      - MCP_REDIRECT_URIS=${MCP_REDIRECT_URIS:-}
       - CORS_ORIGINS=${CORS_ORIGINS:-https://claude.ai}
       - NODE_ENV=production
     extra_hosts:
@@ -49,6 +51,9 @@ MCP_CLIENT_SECRET=your-client-secret
 # Enable OAuth (required for production SSE)
 AUTH_ENABLED=true
 
+# Public URL (required when behind a reverse proxy)
+MCP_ISSUER_URL=https://mcp.your-domain.com
+
 # Allowed CORS origins
 CORS_ORIGINS=https://claude.ai
 ```
@@ -76,3 +81,104 @@ docker compose up -d
 - [ ] `OPENCLAW_GATEWAY_TOKEN` set for gateway authentication
 - [ ] Dynamic client registration is disabled (default — no `/register` endpoint)
 - [ ] Container runs read-only with no-new-privileges
+
+## Reverse Proxy (HTTPS)
+
+The MCP bridge must be served over HTTPS for production use. Use a reverse proxy that handles TLS termination.
+
+> **Important:** You **must** set `MCP_ISSUER_URL` to your public HTTPS URL. Without this, OAuth metadata endpoints will advertise `http://localhost:3000` and MCP clients (including Claude.ai) will fail to authenticate with the error: `Protected resource http://localhost:3000/mcp does not match expected https://your-domain.com/mcp`.
+
+### Caddy (recommended)
+
+Caddy automatically provisions Let's Encrypt certificates.
+
+```
+mcp.your-domain.com {
+    reverse_proxy openclaw-mcp:3000
+}
+```
+
+Add to your `docker-compose.yml`:
+
+```yaml
+services:
+  caddy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    ports:
+      - "80:80"
+      - "443:443"
+      - "443:443/udp"
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy-data:/data
+      - caddy-config:/config
+
+  mcp-bridge:
+    # ... (same as above, but remove the ports section)
+    expose:
+      - "3000"
+    environment:
+      - MCP_ISSUER_URL=https://mcp.your-domain.com
+      # ... other env vars
+
+volumes:
+  caddy-data:
+  caddy-config:
+```
+
+### nginx
+
+```nginx
+server {
+    listen 443 ssl http2;
+    server_name mcp.your-domain.com;
+
+    ssl_certificate /path/to/cert.pem;
+    ssl_certificate_key /path/to/key.pem;
+
+    location / {
+        proxy_pass http://localhost:3000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+        proxy_set_header Host $host;
+        proxy_set_header X-Forwarded-Proto $scheme;
+    }
+}
+```
+
+## OpenClaw Gateway Prerequisites
+
+The MCP bridge communicates with the OpenClaw gateway via its OpenAI-compatible HTTP API (`/v1/chat/completions`). This endpoint is **disabled by default** — you must enable it in your OpenClaw config:
+
+```json5
+// openclaw.json
+{
+  "gateway": {
+    "http": {
+      "endpoints": {
+        "chatCompletions": {
+          "enabled": true
+        }
+      }
+    }
+  }
+}
+```
+
+Without this, the MCP bridge will receive `405 Method Not Allowed` from the gateway.
+
+## Troubleshooting
+
+### `405 Method Not Allowed` from gateway
+
+The OpenClaw gateway's HTTP chat completions endpoint is disabled by default. Enable it in `openclaw.json` — see [Gateway Prerequisites](#openclaw-gateway-prerequisites) above.
+
+### `Protected resource http://localhost:3000/mcp does not match expected https://...`
+
+You're running behind a reverse proxy but haven't set `MCP_ISSUER_URL`. The OAuth metadata endpoints are advertising `http://localhost:3000` instead of your public HTTPS URL. Set `MCP_ISSUER_URL` to your public URL (e.g., `https://mcp.your-domain.com`) or pass `--issuer-url` on the CLI.
+
+### `fetch failed` / MCP bridge can't reach gateway
+
+When both services run in Docker, the MCP bridge must connect via the Docker network hostname (e.g., `http://openclaw-gateway:18789`), not `localhost`. Make sure both containers are on the same Docker network.

package/docs/installation.md

@@ -97,6 +97,10 @@ Options:
   --auth              Enable OAuth             [default: false]
   --client-id         MCP OAuth client ID      [env: MCP_CLIENT_ID]
   --client-secret     MCP OAuth client secret  [env: MCP_CLIENT_SECRET]
+  --issuer-url        OAuth issuer URL         [env: MCP_ISSUER_URL]
+  --redirect-uris     Allowed redirect URIs    [env: MCP_REDIRECT_URIS]
   --version           Show version number
   --help              Show help
 ```
+
+> **Note:** `--issuer-url` is required when running behind a reverse proxy (Caddy, nginx, etc.) so that OAuth metadata endpoints return the correct public HTTPS URL instead of `http://localhost:3000`.

package/docs/logging.md

@@ -0,0 +1,102 @@
+# Logging
+
+## Overview
+
+The MCP server logs operational events to **stderr** using the `[openclaw-mcp]` prefix. Stderr is used (instead of stdout) because the stdio MCP transport uses stdout for protocol messages.
+
+## Log Levels
+
+| Level | Prefix | When |
+|-------|--------|------|
+| Info | `[openclaw-mcp]` | Normal operations — startup, connections, shutdown |
+| Error | `[openclaw-mcp] ERROR:` | Failures — connection errors, invalid config, fatal errors |
+| Debug | `[openclaw-mcp] DEBUG:` | Verbose output — only when `DEBUG=true` or `NODE_ENV=development` |
+
+## What Gets Logged
+
+### Startup
+
+- Server name and version
+- OpenClaw gateway URL (host only, no tokens)
+- Transport type (stdio or SSE)
+- Whether a gateway token is configured (yes/no, not the token itself)
+- OAuth client ID (when auth is enabled)
+- Listening address and port (SSE mode)
+- CORS origins configuration
+
+### Connections (SSE/HTTP transport)
+
+- SSE session connected/disconnected (with session ID)
+- Streamable HTTP session initialized/closed (with session ID)
+
+### Errors
+
+- Gateway connection failures
+- Request timeouts
+- Invalid client configuration (missing secrets, bad client ID format)
+- Session errors
+
+### What Is NOT Logged
+
+- **Message content** — user messages and OpenClaw responses are never logged
+- **Authentication tokens** — Bearer tokens, client secrets, gateway tokens
+- **Request/response bodies** — only error messages, not full payloads
+- **User-identifiable information** — no IPs, user agents, or personal data
+
+## Sensitive Data Redaction
+
+The logger automatically redacts patterns that look like credentials:
+
+- `Bearer <token>` -> `[REDACTED]`
+- `api_key=<value>` -> `[REDACTED]`
+- `token=<value>` -> `[REDACTED]`
+- `secret=<value>` -> `[REDACTED]`
+- `password=<value>` -> `[REDACTED]`
+
+This is a safety net — the code avoids logging sensitive values in the first place, but the redaction layer catches accidental exposure.
+
+## Log Destination
+
+| Transport | Destination | Notes |
+|-----------|-------------|-------|
+| stdio | stderr | Cannot use stdout (reserved for MCP protocol) |
+| SSE/HTTP | stderr | Same format, same destination |
+| Docker | `docker logs openclaw-mcp` | stderr is captured by Docker's log driver |
+
+## Docker Log Management
+
+When running in Docker, logs are managed by the Docker log driver:
+
+```bash
+# View logs
+docker logs openclaw-mcp
+
+# Follow logs
+docker logs -f openclaw-mcp
+
+# Last 100 lines
+docker logs --tail 100 openclaw-mcp
+```
+
+To configure log rotation in `docker-compose.yml`:
+
+```yaml
+services:
+  mcp-bridge:
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"
+```
+
+## Enabling Debug Logs
+
+Set either environment variable:
+
+```bash
+DEBUG=true        # Explicit debug flag
+NODE_ENV=development  # Development mode
+```
+
+Debug logs include additional operational detail but still never log message content or credentials.

package/docs/threat-model.md

@@ -0,0 +1,116 @@
+# Threat Model
+
+## Architecture Overview
+
+```
+Claude (Desktop / Claude.ai)
+    |
+    | MCP Protocol (stdio or SSE/Streamable HTTP)
+    v
+OpenClaw MCP Server (this project)
+    |
+    | OpenAI-compatible REST API (POST /v1/chat/completions)
+    v
+OpenClaw Gateway (user-controlled)
+```
+
+The MCP server is a **stateless proxy** — it translates MCP tool calls into OpenAI-compatible API requests and returns the response. It does not execute code, access the filesystem, or modify any external state on its own.
+
+## What Claude Can Do (via MCP tools)
+
+| Tool | Action | Side Effects |
+|------|--------|--------------|
+| `openclaw_chat` | Send a text message to OpenClaw, receive a text response | None — read-only query |
+| `openclaw_status` | Check if the OpenClaw gateway is reachable | None — health check only |
+| `openclaw_chat_async` | Queue a message for async processing, receive a task ID | Creates an in-memory task |
+| `openclaw_task_status` | Check the status of an async task by ID | None — read-only |
+| `openclaw_task_list` | List all async tasks and their statuses | None — read-only |
+| `openclaw_task_cancel` | Cancel a pending async task by ID | Removes an in-memory task |
+
+**Key point:** All tools either read data or send text messages to OpenClaw. The MCP server itself has **no write access** to any filesystem, database, or external service beyond the OpenClaw gateway.
+
+## What Claude Cannot Do
+
+- **Execute shell commands** — the server has no shell execution capability
+- **Read or write files** — no filesystem access (Docker enforces `read_only: true`)
+- **Access the network** — can only reach the configured OpenClaw gateway URL
+- **Modify server configuration** — environment variables are set at startup, not changeable at runtime
+- **Bypass authentication** — OAuth tokens are validated per-request when auth is enabled
+- **Access other users' sessions** — sessions are isolated by MCP session ID
+
+## Trust Boundaries
+
+### Boundary 1: Claude <-> MCP Server
+
+- **stdio transport (local):** Trusted — communication stays on the local machine. No authentication required.
+- **SSE/HTTP transport (remote):** Untrusted network — requires OAuth 2.1 authentication, HTTPS (via reverse proxy), and CORS restrictions.
+
+### Boundary 2: MCP Server <-> OpenClaw Gateway
+
+- The MCP server authenticates to the gateway using a Bearer token (`OPENCLAW_GATEWAY_TOKEN`).
+- The server validates the gateway URL at startup and blocks requests to private IP ranges (SSRF protection).
+- Responses from the gateway are size-limited (10 MB max) and parsed as JSON — no raw pass-through.
+
+### Boundary 3: User <-> Claude
+
+- Claude decides which MCP tools to call and with what arguments. The MCP server validates all tool inputs (string length, type, format) but **cannot control Claude's intent**.
+- If OpenClaw can perform actions with real-world consequences (e.g., sending emails, modifying data), those consequences are ultimately triggered by Claude's tool calls through the gateway.
+
+## Attack Surfaces
+
+### 1. Malicious MCP Tool Input
+
+**Risk:** Crafted tool arguments could exploit the OpenClaw gateway.
+
+**Mitigations:**
+- All tool inputs are validated: type checks, string length limits, control character rejection
+- The MCP server does not interpret message content — it passes validated strings to the gateway
+
+### 2. Compromised OpenClaw Gateway
+
+**Risk:** A compromised gateway could return malicious responses.
+
+**Mitigations:**
+- Response size limit (10 MB) prevents memory exhaustion
+- Responses are parsed as JSON — no script execution
+- Error messages from the gateway are sanitized before being returned to Claude
+
+### 3. Network-Level Attacks (SSE transport)
+
+**Risk:** Man-in-the-middle, replay attacks, unauthorized access.
+
+**Mitigations:**
+- OAuth 2.1 with client credentials (required for production)
+- HTTPS via reverse proxy (Caddy or nginx)
+- CORS restricted to configured origins (default: `https://claude.ai`)
+- DNS rebinding protection via MCP SDK's Express middleware
+
+### 4. Server-Side Request Forgery (SSRF)
+
+**Risk:** Attacker could trick the server into making requests to internal services.
+
+**Mitigations:**
+- Only one outbound destination: the configured `OPENCLAW_URL`
+- Private IP ranges are blocked at the client level
+- URL is set at startup via environment variable, not controllable via tool input
+
+### 5. Denial of Service
+
+**Risk:** Resource exhaustion through excessive requests or large payloads.
+
+**Mitigations:**
+- Request timeout: 30 seconds per gateway call
+- Response size limit: 10 MB
+- Docker memory limit: 256 MB (configurable)
+- Async task queue is in-memory with bounded processing
+
+## Production Recommendations
+
+If you expose this server beyond localhost:
+
+1. **Enable OAuth 2.1** — set `AUTH_ENABLED=true` with strong client credentials
+2. **Use HTTPS** — terminate TLS at a reverse proxy (Caddy recommended)
+3. **Restrict CORS** — set `CORS_ORIGINS=https://claude.ai` (or your specific origin)
+4. **Run in Docker** — use the provided `docker-compose.yml` with `read_only` and `no-new-privileges`
+5. **Review gateway permissions** — the MCP server is only as safe as what the OpenClaw gateway allows. If OpenClaw can perform destructive actions, consider adding tool allowlists and human approval on the gateway side
+6. **Monitor logs** — see [Logging](./logging.md) for what gets logged and where

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Model Context Protocol (MCP) server for OpenClaw AI assistant integration",
   "author": "Tomáš Grasl <https://www.tomasgrasl.cz/>",
   "license": "MIT",