# MCP OpenClaw

A Model Context Protocol (MCP) server that integrates with the OpenClaw API, enabling AI assistants to send messages, execute commands, manage calendar events, send emails, and track task status.

## Features

- **Send Messages**: Send messages to Telegram, WhatsApp, and Discord
- **Execute Commands**: Run commands in the OpenClaw environment (sync or async)
- **Calendar Management**: Create calendar events with attendees and reminders
- **Email**: Send emails with support for CC/BCC
- **Task Status**: Track the status of asynchronous commands

## Installation

### Global Installation

```bash
npm install -g mcp-openclaw
```

### Local Installation

```bash
npm install mcp-openclaw
```

## Configuration

Set the following environment variables:

```bash
export OPENCLAW_API_URL="https://api.openclaw.example.com"
export OPENCLAW_API_KEY="your-api-key-here"
```

Optional configuration:

```bash
export OPENCLAW_TIMEOUT="30000"        # Request timeout in milliseconds (default: 30000)
export OPENCLAW_MAX_RETRIES="3"        # Maximum retry attempts (default: 3)
export SERVER_NAME="mcp-openclaw"      # Server name (default: mcp-openclaw)
export SERVER_VERSION="1.0.0"          # Server version (default: 1.0.0)
export LOG_LEVEL="info"                # Log level: debug, info, warn, error (default: info)
```

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "openclaw": {
      "command": "node",
      "args": ["/path/to/mcp-openclaw/dist/index.js"],
      "env": {
        "OPENCLAW_API_URL": "https://api.openclaw.example.com",
        "OPENCLAW_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Available Tools

#### 1. send_message

Send a message to a supported platform.

```json
{
  "platform": "telegram",
  "recipient": "@username",
  "message": "Hello from OpenClaw!"
}
```

Supported platforms: `telegram`, `whatsapp`, `discord`

#### 2. execute_command

Execute a command in the OpenClaw environment.

```json
{
  "command": "ls -la",
  "timeout": 30,
  "async": false
}
```

#### 3. create_calendar_event

Create a new calendar event.

```json
{
  "title": "Team Meeting",
  "description": "Weekly team sync",
  "startTime": "2024-01-15T10:00:00Z",
  "endTime": "2024-01-15T11:00:00Z",
  "location": "Conference Room A",
  "attendees": ["user1@example.com", "user2@example.com"],
  "reminder": 15
}
```

#### 4. send_email

Send an email.

```json
{
  "to": "recipient@example.com",
  "subject": "Hello from OpenClaw",
  "body": "This is the email content",
  "cc": "cc@example.com",
  "bcc": "bcc@example.com",
  "html": false
}
```

#### 5. get_task_status

Check the status of an asynchronous command.

```json
{
  "taskId": "task-abc123"
}
```

## Development

### Setup

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

### Build

```bash
npm run build
```

### Test

```bash
npm test
```

### Lint

```bash
npm run lint
npm run lint:fix
```

### Format

```bash
npm run format
```

## Project Structure

```
mcp-openclaw/
├── src/
│   ├── index.ts              # MCP Server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── openclaw-client.ts    # OpenClaw API client
│   └── tools/
│       ├── index.ts          # Tools registry
│       ├── send-message.ts
│       ├── execute-command.ts
│       ├── create-calendar-event.ts
│       ├── send-email.ts
│       └── get-task-status.ts
├── tests/                    # Test files
├── examples/                 # Usage examples
├── docs/                     # Documentation
└── scripts/                  # Build and utility scripts
```

## Architecture

For detailed architecture information, see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).

## API Reference

For the complete API reference, see [docs/API.md](docs/API.md).

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT License - see [LICENSE](LICENSE) for details.

## Changelog

See [CHANGELOG.md](CHANGELOG.md) for version history.

## Support

- Issues: [GitHub Issues](https://github.com/yourusername/mcp-openclaw/issues)
- Documentation: [docs/](docs/)