OpenClaw MCP Server — Claude Code MCP server: bridge to OpenClaw
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.
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-mcpWhat OpenClaw MCP Server 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".
What it helps with
- 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 for the agent
- 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
How to install OpenClaw MCP Server
Platform CLI
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-mcpReplace <…> with your own values
Platform CLI
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-mcpReplace <…> with your own values
Config file
{
"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
Config file
{
"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
Platform CLI
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-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about OpenClaw MCP Server
How do I install OpenClaw MCP Server in Claude Code?
Add the server with claude mcp add openclaw-mcp -e OPENCLAW_URL=<OPENCLAW_URL> -e OPENCLAW_GATEWAY_TOKEN=<OPENCLAW_GATEWAY_TOKEN> -- npx -y openclaw-mcp.
What does OpenClaw MCP Server do?
It exposes OpenClaw tools to an MCP client: chat, gateway health, instance listing, and a queue of async tasks you can check or cancel.
Why does OAuth fail behind a reverse proxy?
Set MCP_ISSUER_URL to your public HTTPS URL and TRUST_PROXY=1. Otherwise the metadata points at localhost and /token crashes on the X-Forwarded-For header.
