# OpenClaw MCP Server

Model Context Protocol (MCP) server for delegating tasks to OpenClaw agents.

## Overview

This MCP server exposes OpenClaw agent capabilities to MCP clients like Cursor, allowing you to:

- Send immediate messages to agents (quick questions, status checks)
- Spawn background tasks (long-running research, monitoring)
- Check task status
- List active sessions

## Installation

### Prerequisites

- Node.js 20+
- OpenClaw CLI installed and configured
- OpenClaw Gateway running

### Quick Install

```bash
# Clone the repo
git clone https://github.com/phoenix-infinex/openclaw-mcp.git
cd openclaw-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Install CLI tools (optional)
sudo ln -sf $(pwd)/bin/tron-delegate /usr/local/bin/tron-delegate
sudo ln -sf $(pwd)/bin/tron-spawn /usr/local/bin/tron-spawn
```

## Configuration

### For Cursor

Add to Cursor's MCP settings:

**Location:** `~/Library/Application Support/Cursor/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json`

```json
{
  "mcpServers": {
    "openclaw": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/openclaw-mcp/dist/index.js"],
      "env": {
        "OPENCLAW_GATEWAY_URL": "ws://localhost:18789",
        "OPENCLAW_AGENT": "phoenix"
      }
    }
  }
}
```

**Get absolute path:**
```bash
cd openclaw-mcp && pwd
# Use: <that_path>/dist/index.js
```

**Restart Cursor** completely after adding config.

### Environment Variables

- `OPENCLAW_GATEWAY_URL` - Gateway WebSocket URL (default: `ws://localhost:18789`)
- `OPENCLAW_AGENT` - Default agent ID (default: `phoenix`)
- `OPENCLAW_TOKEN` - Optional authentication token

## Usage

### From Cursor Chat

Once configured, use OpenClaw tools directly in Cursor:

#### Quick Message
```
Use openclaw to ask: "Check Datadog for any active alerts"
```

#### Background Task
```
Use openclaw to spawn a task: "Monitor Datadog for the next 2 hours and alert me if CPU exceeds 80%"
```

#### Check Status
```
Use openclaw to check status of task: spawn-abc123
```

#### List Sessions
```
Use openclaw to list active sessions
```

### From Terminal (CLI Tools)

#### tron-delegate
Send immediate message to Tron:

```bash
tron-delegate "Check Datadog alerts"
tron-delegate "What's the status of the Coder deployment?"
```

#### tron-spawn
Spawn background task:

```bash
tron-spawn "Monitor Coder pods for 1 hour, alert if crashes"
tron-spawn "Research K8s security best practices"
```

## MCP Tools

### 1. send_message

Send immediate message to an agent (conversational).

**Parameters:**
- `message` (required): Message text
- `agent` (optional): Agent ID (default: from env)
- `timeout` (optional): Timeout in seconds (default: 60)

**Returns:**
```json
{
  "response": "Agent response text",
  "sessionKey": "agent:phoenix:main"
}
```

**Use case:** Quick questions, status checks

---

### 2. spawn_task

Spawn isolated background task (async, long-running).

**Parameters:**
- `task` (required): Task description
- `agent` (optional): Agent ID (default: from env)
- `label` (optional): Task label
- `cleanup` (optional): "keep" or "delete" (default: keep)
- `model` (optional): Model override (e.g., "sonnet")
- `timeout` (optional): Timeout in seconds (default: 300)

**Returns:**
```json
{
  "taskId": "spawn-abc123",
  "sessionKey": "agent:phoenix:isolated:spawn-abc123",
  "status": "running"
}
```

**Use case:** Research, monitoring, batch processing

---

### 3. check_status

Check status of a spawned task.

**Parameters:**
- `taskId` (required): Task ID from spawn_task

**Returns:**
```json
{
  "status": "completed",
  "result": "Task results here",
  "startedAt": "2026-02-18T01:30:00Z",
  "completedAt": "2026-02-18T03:30:00Z"
}
```

---

### 4. list_sessions

List active sessions for an agent.

**Parameters:**
- `agent` (optional): Agent ID (default: from env)
- `activeMinutes` (optional): Filter by activity (default: 60)

**Returns:**
```json
{
  "sessions": [
    {
      "sessionKey": "agent:phoenix:main",
      "kind": "direct",
      "lastUpdate": "2026-02-18T01:35:00Z"
    }
  ]
}
```

## Use Cases

### Quick Infrastructure Check
```
"Use openclaw to check if there are any Datadog alerts"
```
→ Immediate response from Tron

### Long Research Task
```
"Use openclaw to spawn: Research and document the top 5 Kubernetes security vulnerabilities from 2025"
```
→ Background task, notification when done

### Monitoring
```
"Use openclaw to spawn: Monitor the Coder deployment in the coder namespace for the next hour, alert if pods restart"
```
→ Active monitoring

### Status Check
```
"Use openclaw to check what tasks are currently running"
```
→ See active sessions

## Development

### Build
```bash
npm run build
```

### Watch Mode
```bash
npm run dev
```

### Test
```bash
./test.sh
```

## Architecture

```
┌──────────┐         ┌──────────────┐         ┌──────────────┐
│  Cursor  │  stdio  │  OpenClaw    │   CLI   │  OpenClaw    │
│  (IDE)   │◄───────►│  MCP Server  │◄───────►│   Gateway    │
└──────────┘         └──────────────┘         └──────────────┘
     │                      │
     │                      └─ Uses `openclaw` CLI
     │                         - sessions send
     │                         - sessions spawn
     └─ MCP protocol          - sessions list
```

## Troubleshooting

### Server not starting in Cursor

1. **Check absolute paths in config**
   ```bash
   cd openclaw-mcp && pwd
   # Use full path + /dist/index.js
   ```

2. **Verify Node.js version**
   ```bash
   node --version  # Need v20+
   ```

3. **Check build succeeded**
   ```bash
   ls dist/
   # Should see: index.js, openclaw.js, types.js
   ```

4. **Look at Cursor logs**
   - In Cursor: Help → Show Logs
   - Search for "mcp" or "openclaw"

### Commands failing

1. **Verify OpenClaw CLI works**
   ```bash
   openclaw status
   openclaw sessions list
   ```

2. **Check Gateway is running**
   ```bash
   openclaw gateway status
   ```

3. **Test agent exists**
   ```bash
   openclaw sessions send --agent phoenix --message "test"
   ```

### CLI tools not found

After symlinking, reload shell or add to PATH:

```bash
# In ~/.zshrc or ~/.bashrc
export PATH="$HOME/openclaw-mcp/bin:$PATH"
```

## Project Structure

```
openclaw-mcp/
├── src/
│   ├── index.ts          # Main MCP server
│   ├── openclaw.ts       # OpenClaw client wrapper
│   └── types.ts          # TypeScript types
├── bin/
│   ├── tron-delegate     # Quick delegation CLI
│   └── tron-spawn        # Background task CLI
├── dist/                 # Built JS files (after npm run build)
├── package.json          # Dependencies
├── tsconfig.json         # TypeScript config
├── README.md             # This file
├── SETUP.md              # Quick setup guide
└── test.sh               # Validation script
```

## Roadmap

**Current (MVP):**
- ✅ Basic tool implementations
- ✅ CLI-based communication
- ✅ Cursor integration
- ✅ CLI tools for terminal use

**Future:**
- [ ] Direct WebSocket communication (faster)
- [ ] Real-time task progress updates
- [ ] Better error handling
- [ ] Session history queries
- [ ] Multi-agent support
- [ ] Authentication tokens

## License

MIT

---

**Created:** 2026-02-18  
**Author:** Tron (phoenix agent)  
**For:** Phoenix @ Infinex