# openclaw-mcp

MCP (Model Context Protocol) server that bridges AI assistants with [OpenClaw](https://github.com/openclaw/openclaw) Gateway.

This lets AI assistants like **Cursor** and **Claude Desktop** talk directly to your OpenClaw agent through MCP tools.

## Features

| Tool | Description |
|------|-------------|
| `openclaw_chat` | Send a message to OpenClaw agent and get the response |
| `openclaw_history` | Read recent chat history from the current session |
| `openclaw_sessions` | List all OpenClaw sessions |
| `openclaw_read_file` | Read agent workspace files (SOUL.md, MEMORY.md, etc.) |
| `openclaw_list_files` | List files in the agent workspace directory |

## Prerequisites

- [OpenClaw](https://github.com/openclaw/openclaw) installed and configured (source checkout with `pnpm install`)
- OpenClaw Gateway running (`openclaw gateway run` or systemd service)
- Node.js 22+

## Install

```bash
git clone https://github.com/YOUR_USERNAME/openclaw-mcp.git
cd openclaw-mcp
npm install
```

## Configure Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "openclaw": {
      "command": "npx",
      "args": ["tsx", "/path/to/openclaw-mcp/server.ts"],
      "env": {
        "OPENCLAW_DIR": "/path/to/openclaw",
        "OPENCLAW_AGENT_WORKSPACE": "/path/to/clawd"
      }
    }
  }
}
```

## Configure Claude Desktop

Add to Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "openclaw": {
      "command": "npx",
      "args": ["tsx", "/path/to/openclaw-mcp/server.ts"],
      "env": {
        "OPENCLAW_DIR": "/path/to/openclaw",
        "OPENCLAW_AGENT_WORKSPACE": "/path/to/clawd"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `OPENCLAW_DIR` | `~/openclaw` | Path to OpenClaw source checkout |
| `OPENCLAW_AGENTS_DIR` | `~/.openclaw/agents` | Path to agent sessions directory |
| `OPENCLAW_AGENT_WORKSPACE` | `~/clawd` | Path to agent workspace (SOUL.md, etc.) |

## How It Works

```
Cursor/Claude ──MCP──> openclaw-mcp ──CLI──> pnpm openclaw agent ──> OpenClaw Gateway ──> AI Model
```

The MCP server calls `pnpm openclaw agent --message "..." --json` under the hood, which communicates with the OpenClaw Gateway via WebSocket. This ensures all OpenClaw skills, tools, and agent capabilities are available.

## License

MIT