# freema/openclaw-mcp [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/freema/openclaw-mcp  
**GitHub Stars:** 188  
**npm Downloads (last month):** 588  
**Views:** 8  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/freema-openclaw-mcp

## Description
MCP server for OpenClaw AI assistant integration. Enables Claude to delegate tasks to OpenClaw agents with sync/async tools, OAuth 2.1 auth, and SSE transport for Claude.ai.

## Tools
Capabilities this server exposes over MCP:

- **openclaw_chat** — Send a message to OpenClaw and get a response
- **openclaw_status** — Get OpenClaw gateway status and health information
- **openclaw_chat_async** — Send a message to OpenClaw asynchronously. Returns a task_id immediately that can be polled for results. Use this for potentially long-running conversations.
- **openclaw_task_status** — Check the status of an async task. Returns status, and result if completed.
- **openclaw_task_list** — List all tasks. Optionally filter by status, session, or instance.
- **openclaw_task_cancel** — Cancel a pending task. Only works for tasks that haven't started yet.
- **openclaw_instances** — List all configured OpenClaw instances. Shows instance names, URLs, and which is the default. Use instance names in other tools to target a specific OpenClaw gateway.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "openclaw-mcp": {
    "command": "npx",
    "args": ["openclaw-mcp"],
    "env": {
      "OPENCLAW_URL": "",
      "OPENCLAW_GATEWAY_TOKEN": "",
      "OPENCLAW_AGENT_ID": "",
      "OPENCLAW_MODEL": "",
      "OPENCLAW_TIMEOUT_MS": "",
      "MCP_CLIENT_ID": "",
      "MCP_CLIENT_SECRET": "",
      "MCP_ISSUER_URL": ""
    }
  }
}
```

**Requires environment variables:** `OPENCLAW_URL`, `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_AGENT_ID`, `OPENCLAW_MODEL`, `OPENCLAW_TIMEOUT_MS`, `MCP_CLIENT_ID`, `MCP_CLIENT_SECRET`, `MCP_ISSUER_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What freema/openclaw-mcp does

freema/openclaw-mcp bridges MCP clients and OpenClaw AI assistant gateways. It lets a connected client send messages to OpenClaw, retrieve responses, inspect gateway health, and select among configured OpenClaw instances.

The bridge supports both immediate and deferred conversations. Synchronous chat waits for a response, while asynchronous chat returns a task identifier so longer operations can be checked separately. Task tools cover status lookup, listing, and cancellation of queued work.

A single bridge can be configured with multiple OpenClaw gateways, such as separate development, staging, and production instances. Each instance can have its own URL, authentication, and timeout settings, and tools can target an instance by name.

## How it works

For local use, the package runs as an MCP process over stdio. Claude Desktop starts it with `npx openclaw-mcp`, and the bridge communicates with an OpenClaw gateway at the configured URL.

For remote use, start the server with the HTTP transport and expose its `/mcp` endpoint through HTTPS. The remote setup uses OAuth 2.1, CORS controls, and configurable redirect URIs for Claude.ai. When a reverse proxy is involved, the public issuer URL and proxy trust setting must match the deployment so OAuth metadata and forwarded request handling work correctly.

Asynchronous tasks belong to the MCP connection that created them. In HTTP mode, clients can only inspect or cancel tasks from that same connection; reconnecting creates a new task scope.

## Setup and configuration

The Docker image is available from GitHub Container Registry, and the package can also be launched with `npx`. A basic local configuration supplies the OpenClaw URL and gateway token, with optional agent, model, and timeout settings.

For an HTTP deployment, configure an MCP client ID and secret. Set `MCP_ISSUER_URL` to the public HTTPS address when using a reverse proxy, and set `TRUST_PROXY=1` in that arrangement. Claude.ai connector URLs must end in `/mcp`; using the bare domain targets the server root instead of the MCP endpoint.

The deployment examples use port 3000 for the bridge and port 18789 for an OpenClaw gateway. Claude.ai setups can restrict authorization callbacks with `MCP_REDIRECT_URIS`, including the exact callback paths used by Claude.

## Tools and capabilities

- `openclaw_chat` sends a message and waits for the OpenClaw response.
- `openclaw_chat_async` queues a message and immediately returns a `task_id`.
- `openclaw_task_status` retrieves the state and completed result of an asynchronous task.
- `openclaw_task_list` lists tasks, with optional status, session, or instance filtering.
- `openclaw_task_cancel` cancels a task that has not started.
- `openclaw_status` checks gateway health information.
- `openclaw_instances` lists configured gateways, their URLs, and the default instance.

## Limitations and notes

Cancellation only applies to pending tasks. Task identifiers are scoped to their creating MCP connection, so a task may appear unavailable after reconnecting or when queried by another HTTP client. Remote deployments also need correct HTTPS, OAuth issuer, redirect URI, and proxy settings for Claude.ai authentication.

_Full upstream README: https://allmcps.com/mcp/freema-openclaw-mcp/readme_