# 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
