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

# 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

{
  "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:

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:

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

tron-spawn

Spawn background task:

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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

npm run build

Watch Mode

npm run dev

Test

./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

   cd openclaw-mcp && pwd
   # Use full path + /dist/index.js

2. Verify Node.js version

   node --version  # Need v20+

3. Check build succeeded

   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

   openclaw status
   openclaw sessions list

2. Check Gateway is running

   openclaw gateway status

3. Test agent exists

   openclaw sessions send --agent phoenix --message "test"

CLI tools not found

After symlinking, reload shell or add to PATH:

# 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