# OpenClaw MCP Server

Bridges Claude.ai and Claude Desktop to your self-hosted OpenClaw over OAuth 2.1. Useful when you want to hand tasks to the bot from chat.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 188
- Author: freema
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/freema/openclaw-mcp
- Updated: 2026-09-19
- HTML: https://affpapa.org/en/nevibecode/mcp/openclaw-mcp-server

## What it does

The server runs a bridge between an MCP client and the OpenClaw gateway on port `18789`. Your chat delegates a task to the bot, and the bot handles the rest, up to launching Claude to fix things. Sync tools `openclaw_chat`, `openclaw_status` and `openclaw_instances` answer right away; async tools `openclaw_chat_async`, `openclaw_task_status`, `openclaw_task_list` and `openclaw_task_cancel` queue the work and hand back a `task_id`.

Two ways to run it. A Docker image sits in GitHub Container Registry, configured through `docker-compose.yml` with `OPENCLAW_URL`, `OPENCLAW_GATEWAY_TOKEN` and the `MCP_CLIENT_SECRET` secret. For Claude Desktop, `npx openclaw-mcp` plus a config entry is enough. There is also an HTTP mode behind a reverse proxy.

Behind a proxy you must set `MCP_ISSUER_URL` to your public HTTPS URL and `TRUST_PROXY=1`. Without the first, OAuth metadata advertises `http://localhost:3000` and clients fail to authenticate. Without the second, `express-rate-limit` rejects the `X-Forwarded-For` header and `/token` crashes with `ERR_ERL_UNEXPECTED_X_FORWARDED_FOR`. In Claude.ai the connector URL has to end with `/mcp`; a bare domain returns 404 after OAuth. Tasks are scoped to the connection, so in HTTP mode another client's `task_id` reads as "not found".

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `OPENCLAW_URL`, `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_MODEL`, `OPENCLAW_TIMEOUT_MS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env OPENCLAW_URL=<OPENCLAW_URL> --env OPENCLAW_GATEWAY_TOKEN=<OPENCLAW_GATEWAY_TOKEN> --env OPENCLAW_MODEL=<OPENCLAW_MODEL> --env OPENCLAW_TIMEOUT_MS=<OPENCLAW_TIMEOUT_MS> --transport stdio openclaw-mcp-server -- npx -y openclaw-mcp
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add openclaw-mcp-server --env OPENCLAW_URL=<OPENCLAW_URL> --env OPENCLAW_GATEWAY_TOKEN=<OPENCLAW_GATEWAY_TOKEN> --env OPENCLAW_MODEL=<OPENCLAW_MODEL> --env OPENCLAW_TIMEOUT_MS=<OPENCLAW_TIMEOUT_MS> -- npx -y openclaw-mcp
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "openclaw-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "openclaw-mcp"
            ],
            "env": {
                "OPENCLAW_URL": "<OPENCLAW_URL>",
                "OPENCLAW_GATEWAY_TOKEN": "<OPENCLAW_GATEWAY_TOKEN>",
                "OPENCLAW_MODEL": "<OPENCLAW_MODEL>",
                "OPENCLAW_TIMEOUT_MS": "<OPENCLAW_TIMEOUT_MS>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "openclaw-mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "openclaw-mcp"
            ],
            "env": {
                "OPENCLAW_URL": "<OPENCLAW_URL>",
                "OPENCLAW_GATEWAY_TOKEN": "<OPENCLAW_GATEWAY_TOKEN>",
                "OPENCLAW_MODEL": "<OPENCLAW_MODEL>",
                "OPENCLAW_TIMEOUT_MS": "<OPENCLAW_TIMEOUT_MS>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e OPENCLAW_URL=<OPENCLAW_URL> -e OPENCLAW_GATEWAY_TOKEN=<OPENCLAW_GATEWAY_TOKEN> -e OPENCLAW_MODEL=<OPENCLAW_MODEL> -e OPENCLAW_TIMEOUT_MS=<OPENCLAW_TIMEOUT_MS> openclaw-mcp-server npx -y openclaw-mcp
```
Replace <…> with your own values

## When to use it
- send tasks to the OpenClaw bot from Claude.ai chat
- check whether the OpenClaw gateway is up
- queue a long operation and collect the result by task_id
- cancel a stuck task
- list configured OpenClaw instances

## Example prompts
- Send a task to the bot with openclaw_chat and show me the reply
- Check the OpenClaw gateway health with openclaw_status
- Queue this task with openclaw_chat_async and return the task_id

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 386989
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md