# MCP OpenClaw API Reference
This document provides detailed API reference for all tools and types in MCP OpenClaw.
## Table of Contents
- [Tools](#tools)
- [Type Definitions](#type-definitions)
- [Error Handling](#error-handling)
- [Examples](#examples)
---
## Tools
### send_message
Send a message to a supported messaging platform.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| platform | string | Yes | Target platform: `telegram`, `whatsapp`, `discord` |
| recipient | string | Yes | Recipient identifier (username, phone number, etc.) |
| message | string | Yes | Message content to send |
**Response:**
```typescript
{
success: boolean;
platform: string;
recipient: string;
messageId?: string;
message?: string;
error?: string;
}
```
**Example:**
```json
{
"platform": "telegram",
"recipient": "@username",
"message": "Hello from OpenClaw!"
}
```
---
### execute_command
Execute a command in the OpenClaw environment.
**Parameters:**
| Name | Type | Required | Default | Description |
|------|------|----------|---------|-------------|
| command | string | Yes | - | Command to execute |
| timeout | number | No | 30 | Timeout in seconds (1-300) |
| async | boolean | No | false | Execute asynchronously |
**Response (sync):**
```typescript
{
success: boolean;
command: string;
output?: string;
exitCode?: number;
error?: string;
}
```
**Response (async):**
```typescript
{
success: boolean;
command: string;
taskId?: string;
message?: string;
error?: string;
}
```
**Example:**
```json
{
"command": "ls -la",
"timeout": 60,
"async": true
}
```
---
### create_calendar_event
Create a new calendar event.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| title | string | Yes | Event title |
| description | string | No | Event description |
| startTime | string | Yes | Start time (ISO 8601) |
| endTime | string | No | End time (ISO 8601) |
| location | string | No | Event location |
| attendees | string[] | No | Attendee email addresses |
| reminder | number | No | Reminder minutes before event |
**Response:**
```typescript
{
success: boolean;
eventId?: string;
title: string;
startTime: string;
message?: string;
error?: string;
}
```
**Example:**
```json
{
"title": "Team Meeting",
"description": "Weekly sync",
"startTime": "2024-01-15T10:00:00Z",
"endTime": "2024-01-15T11:00:00Z",
"location": "Conference Room A",
"attendees": ["user1@example.com"],
"reminder": 15
}
```
---
### send_email
Send an email to one or more recipients.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| to | string \| string[] | Yes | Primary recipient(s) |
| subject | string | Yes | Email subject |
| body | string | Yes | Email body content |
| cc | string \| string[] | No | CC recipient(s) |
| bcc | string \| string[] | No | BCC recipient(s) |
| html | boolean | No | Body is HTML (default: false) |
**Response:**
```typescript
{
success: boolean;
to: string[];
subject: string;
messageId?: string;
message?: string;
error?: string;
}
```
**Example:**
```json
{
"to": "recipient@example.com",
"subject": "Hello from OpenClaw",
"body": "This is the email content",
"cc": "manager@example.com",
"html": false
}
```
---
### get_task_status
Get the status of an asynchronous task.
**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| taskId | string | Yes | Task identifier from execute_command |
**Response:**
```typescript
{
success: boolean;
taskId?: string;
status?: 'pending' | 'running' | 'completed' | 'failed';
output?: string;
exitCode?: number;
description?: string;
error?: string;
}
```
**Status Values:**
| Status | Description |
|--------|-------------|
| pending | Task is waiting to start |
| running | Task is currently executing |
| completed | Task completed successfully |
| failed | Task failed during execution |
**Example:**
```json
{
"taskId": "task-abc123-def456"
}
```
---
## Type Definitions
### Platform
```typescript
type Platform = 'telegram' | 'whatsapp' | 'discord';
```
### CommandStatus
```typescript
type CommandStatus = 'pending' | 'running' | 'completed' | 'failed';
```
### TaskPriority
```typescript
type TaskPriority = 'low' | 'medium' | 'high' | 'urgent';
```
### OpenClawConfig
```typescript
interface OpenClawConfig {
apiUrl: string;
apiKey: string;
timeout?: number; // Default: 30000
maxRetries?: number; // Default: 3
}
```
### SendMessageParams
```typescript
interface SendMessageParams {
platform: Platform;
recipient: string;
message: string;
}
```
### ExecuteCommandParams
```typescript
interface ExecuteCommandParams {
command: string;
timeout?: number;
async?: boolean;
}
```
### CreateCalendarEventParams
```typescript
interface CreateCalendarEventParams {
title: string;
description?: string;
startTime: string; // ISO 8601
endTime?: string; // ISO 8601
location?: string;
attendees?: string[];
reminder?: number; // minutes before
}
```
### SendEmailParams
```typescript
interface SendEmailParams {
to: string | string[];
subject: string;
body: string;
cc?: string | string[];
bcc?: string | string[];
html?: boolean;
}
```
### GetTaskStatusParams
```typescript
interface GetTaskStatusParams {
taskId: string;
}
```
---
## Error Handling
### Error Response Format
All errors return a consistent format:
```typescript
{
error: string; // Human-readable error message
code?: string; // Machine-readable error code
details?: unknown; // Additional error context
}
```
### Error Codes
| Code | Description |
|------|-------------|
| API_ERROR | General API error |
| HTTP_ERROR | HTTP protocol error |
| NETWORK_ERROR | Network connectivity issue |
| REQUEST_ERROR | Malformed request |
| VALIDATION_ERROR | Input validation failed |
### Common Errors
**Missing Required Parameter:**
```json
{
"error": "Platform is required"
}
```
**Invalid Email Format:**
```json
{
"error": "Invalid email format in to: invalid-email"
}
```
**Invalid Date Format:**
```json
{
"error": "Start time must be in valid ISO 8601 format"
}
```
**API Authentication Failed:**
```json
{
"error": "Authentication failed",
"code": "AUTH_ERROR"
}
```
---
## Examples
### Complete Workflow: Async Command
```typescript
// 1. Start async command
const executeResult = await execute_command({
command: "npm install",
timeout: 120,
async: true
});
// Returns: { success: true, taskId: "task-abc123" }
// 2. Poll for completion
const statusResult = await get_task_status({
taskId: "task-abc123"
});
// Returns: { success: true, status: "running" }
// 3. Get final result
const finalResult = await get_task_status({
taskId: "task-abc123"
});
// Returns: { success: true, status: "completed", exitCode: 0 }
```
### Sending to Multiple Recipients
```typescript
// Email with multiple recipients
await send_email({
to: ["user1@example.com", "user2@example.com"],
subject: "Team Update",
body: "Here is the weekly update...",
cc: "manager@example.com"
});
```
### Calendar Event with All Options
```typescript
await create_calendar_event({
title: "Project Review",
description: "Q4 project milestone review",
startTime: "2024-12-15T14:00:00Z",
endTime: "2024-12-15T15:30:00Z",
location: "Main Conference Room",
attendees: [
"alice@example.com",
"bob@example.com",
"carol@example.com"
],
reminder: 30
});
```
### Platform-Specific Message Formats
```typescript
// Telegram - uses @username or user ID
await send_message({
platform: "telegram",
recipient: "@username",
message: "Hello!"
});
// WhatsApp - uses phone number with country code
await send_message({
platform: "whatsapp",
recipient: "+1234567890",
message: "Hello!"
});
// Discord - uses user ID or channel ID
await send_message({
platform: "discord",
recipient: "123456789012345678",
message: "Hello!"
});
```
