Openclaw MCP

What freema/openclaw-mcp MCP server does

The freema/openclaw-mcp MCP server exposes OpenClaw assistant gateways through MCP tools. A connected client can send a message and wait for the response, check gateway health, or identify the configured OpenClaw instances available for routing. The bridge can target a default gateway or a named instance when multiple gateways are configured.

For work that may take longer, the server supports an asynchronous flow. A client queues a message, receives a task ID, and later checks the task for progress or its completed result. It can also list tasks with optional filters for status, session, or instance, and cancel tasks that have not started.

How it works

The bridge sits between an MCP client and one or more OpenClaw gateways. It communicates with the gateway using the configured OpenClaw URL and gateway token, while presenting MCP tools to the client. Each configured instance can have its own URL, authentication, and timeout settings.

Local use is supported through the standard input/output transport, with Claude Desktop launching the npm package directly. For remote use, the process can run with HTTP transport on a selected port. The documented remote setup uses OAuth 2.1 settings, CORS configuration, and a public issuer URL so Claude.ai can authenticate against the deployment.

Asynchronous tasks are scoped to the MCP connection that created them. In HTTP mode, clients cannot inspect or cancel another client's task, even if they know its task ID. A reconnect creates a new scope, so polling must happen through the same connection that submitted the task.

Setup and configuration

The freema/openclaw-mcp MCP server can be started locally with npx openclaw-mcp. Its local configuration includes OPENCLAW_URL, OPENCLAW_GATEWAY_TOKEN, an optional OPENCLAW_AGENT_ID, an OpenClaw model value, and an optional request timeout. The README uses http://127.0.0.1:18789 as the local gateway URL and main as an example agent ID.

Docker images are published to GitHub Container Registry. The documented container setup maps port 3000, passes the OpenClaw gateway token, and can enable HTTP authentication with AUTH_ENABLED, MCP_CLIENT_ID, and MCP_CLIENT_SECRET. Deployments behind a reverse proxy should set MCP_ISSUER_URL to the public HTTPS address and enable TRUST_PROXY. MCP_REDIRECT_URIS can restrict OAuth callbacks to the documented Claude callback URLs, while CORS_ORIGINS controls the permitted web origin.

When adding the remote server to Claude.ai, use the /mcp endpoint rather than the bare domain. The README states that the connector URL must end in /mcp for the Streamable HTTP endpoint.

Tools and capabilities

• openclaw_chat: send a message and receive a response synchronously.
• openclaw_status: retrieve OpenClaw gateway health and status information.
• openclaw_chat_async: submit a message and immediately receive a task ID.
• openclaw_task_status: inspect an asynchronous task and retrieve its result when complete.
• openclaw_task_list: list tasks, with optional status, session, or instance filters.
• openclaw_task_cancel: cancel a task that has not started.
• openclaw_instances: list configured gateways, their URLs, and the default instance.

The freema/openclaw-mcp MCP server is therefore suited to delegating short chats or longer-running assistant work from Claude while retaining separate routing for development, staging, production, or other named OpenClaw gateways.

Limitations and notes

Task visibility is connection-specific, and cancellation only applies to pending tasks that have not begun. Remote OAuth configuration must match the callback paths exactly; an incorrect redirect URI prevents authorization. The gateway token and, when HTTP authentication is enabled, the MCP client credentials must be supplied by the deployment operator.