How to add OpenClaw MCP Server to Claude Desktop

Secure bridge between Claude.ai/Desktop and a self-hosted OpenClaw AI assistant, with OAuth2 and multi-instance routing. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

Last updated June 14, 2026 · 173★ · stdio · oauth

Claude Desktop config for OpenClaw MCP Server

npx openclaw-mcp

{
  "mcpServers": {
    "openclaw-mcp-server": {
      "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"
      }
    }
  }
}

Setup steps

1Open Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
2Paste the OpenClaw MCP Server config below under the top-level "mcpServers" key.
3Fill in any placeholder secrets (API keys, paths) in the snippet.
4Save the file, then fully quit and reopen Claude Desktop.
5Open a chat and confirm OpenClaw MCP Server's tools appear under the 🔌 tools menu.

Before you start

Node.js >= 20
An OpenClaw gateway running with the HTTP API enabled (gateway.http.endpoints.chatCompletions.enabled = true)
OPENCLAW_GATEWAY_TOKEN for the OpenClaw gateway
For remote (Claude.ai) use: AUTH_ENABLED with MCP_CLIENT_ID / MCP_CLIENT_SECRET, MCP_ISSUER_URL and TRUST_PROXY=1 behind a reverse proxy
Docker (optional, for the GHCR image deployment)

What OpenClaw MCP Server can do in Claude Desktop

openclaw_chat

Send messages to OpenClaw and get responses (synchronous). Accepts an optional instance parameter to target a specific gateway.

openclaw_status

Check OpenClaw gateway health. Accepts an optional instance parameter.

openclaw_instances

List all configured OpenClaw instances (tokens are never exposed).

openclaw_chat_async

Queue a message for a long-running operation and get a task_id immediately. Accepts an optional instance parameter.

openclaw_task_status

Check task progress and get results.

openclaw_task_list

List all tasks with filtering.

openclaw_task_cancel

Cancel a pending task.

Security

Always enable authentication in production: set AUTH_ENABLED=true with MCP_CLIENT_ID and a strong MCP_CLIENT_SECRET (e.g. openssl rand -hex 32). Restrict origins via CORS_ORIGINS (e.g. https://claude.ai). When running behind a reverse proxy you must set MCP_ISSUER_URL to your public HTTPS URL and TRUST_PROXY=1, otherwise OAuth metadata and the /token rate limiter break. The remote connector URL must end with /mcp (the Streamable HTTP endpoint). OAuth 2.1 is used for the remote (Claude.ai) transport; the local stdio transport authenticates to the OpenClaw gateway via OPENCLAW_GATEWAY_TOKEN. Tokens are never exposed via openclaw_instances. The Docker image runs read_only with no-new-privileges.

OpenClaw MCP Server + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the OpenClaw MCP Server config there under the "mcpServers" key and restart the client.

Is OpenClaw MCP Server safe to use with Claude Desktop?

Do I need Docker?

No. Docker is the recommended path for remote (Claude.ai) deployments via the GHCR image, but you can also run it locally with `npx openclaw-mcp` for Claude Desktop, or remotely with `npx openclaw-mcp --transport http --port 3000`.

Why does my Claude.ai connector return 404 after OAuth?

The connector URL must end with /mcp, which is the Streamable HTTP endpoint. A bare domain hits the server root and returns 404 after OAuth completes.

What must I set behind a reverse proxy?

Set MCP_ISSUER_URL (or --issuer-url) to your public HTTPS URL so OAuth metadata is correct, and TRUST_PROXY=1 (or --trust-proxy 1) so express-rate-limit accepts the proxy's X-Forwarded-For header instead of crashing /token.

View repo Full OpenClaw MCP Server page