OpenClaw MCP Server

Project Overview

OpenClaw MCP (Model Context Protocol) server provides a bridge between Claude (Desktop & Claude.ai) and the OpenClaw AI assistant. It implements the MCP specification to expose OpenClaw capabilities as tools that Claude can invoke.

Security Policy (CRITICAL)

This is a security-critical MCP server. Follow these rules:

Docker-First Deployment (MANDATORY)

• Users MUST run this server via Docker in production
• Never run directly on bare metal in production environments
• Docker provides: process isolation, network segmentation, resource limits, reproducible builds
• Use the provided docker-compose.yml for the complete stack

Authentication

• OAuth 2.1 MUST be enabled in production (AUTH_ENABLED=true)
• Set MCP_CLIENT_ID and MCP_CLIENT_SECRET env vars
• Generate secrets with: openssl rand -hex 32
• Never commit secrets to the repository
• Uses MCP SDK's built-in OAuth server (mcpAuthRouter + requireBearerAuth)

Input Validation

• All MCP tool inputs MUST be validated before processing
• Validate string lengths, types, and formats
• Never pass unsanitized input to system calls or APIs

Error Handling

• Never expose stack traces, internal paths, or credentials in error responses
• Log errors server-side, return generic messages to clients

Architecture

Claude Desktop/Claude.ai
    ↕ (MCP Protocol - stdio or SSE)
OpenClaw MCP Server (this project)
    ↕ (OpenAI-compatible REST API: POST /v1/chat/completions)
OpenClaw Gateway (http://localhost:18789)

Gateway API

The OpenClaw gateway exposes an OpenAI-compatible endpoint at POST /v1/chat/completions. Authentication uses a Bearer token (OPENCLAW_GATEWAY_TOKEN).

Transports

• stdio - For local Claude Desktop integration (default)
• SSE - For remote Claude.ai integration (requires OAuth + HTTPS)

Tools

Development

Commands

npm run dev          # Watch mode (tsx)
npm run build        # Production build (tsup)
npm run typecheck    # TypeScript type checking
npm run lint         # ESLint
npm run lint:fix     # ESLint with auto-fix
npm run format       # Prettier formatting
npm run test         # Vitest (watch mode)
npm run test:run     # Vitest (single run)
npm run check:all    # Full validation pipeline

Tech Stack

• TypeScript (ES2022 target, ESM modules)
• Node.js >=20
• Build: tsup (bundles to single dist/index.js)
• Test: vitest
• Lint: eslint + prettier

File Structure

src/
├── index.ts              # Entry point, MCP server setup
├── cli.ts                # CLI argument parsing (yargs)
├── auth/provider.ts      # OAuth 2.1 server provider (MCP SDK)
├── config/constants.ts   # Server constants
├── mcp/tools/            # MCP tool definitions & handlers
├── mcp/tasks/            # Async task manager
├── openclaw/client.ts    # OpenClaw API client (OpenAI-compatible)
├── openclaw/types.ts     # TypeScript type definitions
├── server/sse.ts         # SSE transport (remote access)
└── utils/                # Logger, errors, response helpers

Conventions

• ESM imports with .js extensions (required for ESM compatibility)
• Underscore prefix for unused variables (_var)
• Single quotes, semicolons, 2-space indent, 100 char width
• Custom error classes extend OpenClawError
• All async operations use async/await (no raw promises)

Docker Deployment (Required for Production)

# Quick start
docker compose up -d

# With custom config
cp .env.example .env
# Edit .env with your settings
docker compose up -d

See docs/deployment.md for full production setup including TLS, OAuth, and monitoring.

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.

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_MODEL=openclaw
      - AUTH_ENABLED=true
      - MCP_CLIENT_ID=openclaw
      - MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
      - MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
      - 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 your server with MCP_CLIENT_ID=openclaw and your MCP_CLIENT_SECRET.

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

See Installation Guide for details.

Architecture

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

Async Tools (for long-running operations)

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

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

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:

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

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

Configure CORS to restrict access:

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

See Configuration for all security options.

Requirements

• Node.js ≥ 20
• OpenClaw gateway running with HTTP API enabled:

  // openclaw.json
  { "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } }
  

License

MIT

Author

Created by Tomáš Grasl

Related Projects

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