# 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/)
