https://github.com/freema/openclaw-mcp

🦞 MCP server for OpenClaw - secure bridge between Claude.ai and your self-hosted OpenClaw assistant with OAuth2 authentication
https://github.com/freema/openclaw-mcp

docker-compose mcp-server open-claw productivity security typescript

Last synced: 4 months ago
JSON representation

🦞 MCP server for OpenClaw - secure bridge between Claude.ai and your self-hosted OpenClaw assistant with OAuth2 authentication

Host: GitHub
URL: https://github.com/freema/openclaw-mcp
Owner: freema
Created: 2026-02-02T16:42:53.000Z (5 months ago)
Default Branch: main
Last Pushed: 2026-02-07T21:10:46.000Z (5 months ago)
Last Synced: 2026-02-08T01:09:21.442Z (5 months ago)
Topics: docker-compose, mcp-server, open-claw, productivity, security, typescript
Language: TypeScript
Homepage: https://www.tomasgrasl.cz/
Size: 744 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- Security: SECURITY.md

Awesome Lists containing this project

awesome-claw - freema/openclaw-mcp - Secure bridge between Claude.ai and your self-hosted OpenClaw assistant with OAuth2 authentication (Integrations & Extensions)
awesome-mcp-servers - freema/openclaw-mcp - mcp) 📇 ☁️ 🏠 - سرور MCP برای یکپارچه‌سازی دستیار هوش مصنوعی [OpenClaw](https://github.com/openclaw/openclaw). امکان واگذاری وظایف از Claude به عامل‌های OpenClaw با ابزارهای همگام/ناهمگام، احراز هویت OAuth 2.1 و انتقال SSE برای Claude.ai را فراهم می‌کند. (پیاده‌سازی‌های سرور / 🖥️ <a name="command-line"></a>خط فرمان)
awesome-claw-cn - openclaw-mcp
awesome-openclaw-resources - OpenClaw MCP Bridge - Secure bridge between Claude.ai and self-hosted OpenClaw with OAuth 2.1 authentication and CORS protection. (Open Source Projects / Security)

README

# OpenClaw MCP Server

[![npm version](https://badge.fury.io/js/openclaw-mcp.svg)](https://www.npmjs.com/package/openclaw-mcp)
[![CI](https://github.com/freema/openclaw-mcp/workflows/CI/badge.svg)](https://github.com/freema/openclaw-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GHCR](https://img.shields.io/badge/GHCR-ghcr.io%2Ffreema%2Fopenclaw--mcp-blue?logo=github)](https://github.com/freema/openclaw-mcp/pkgs/container/openclaw-mcp)

🦞 Model Context Protocol (MCP) server for [OpenClaw](https://github.com/openclaw/openclaw) AI assistant integration.

## Demo

OpenClaw MCP in Claude.ai

## Why I Built This

Hey! I created this MCP server because I didn't want to rely solely on messaging channels to communicate with OpenClaw. What really excites me is the ability to connect OpenClaw to the Claude web UI. Essentially, my chat can delegate tasks to my Claw bot, which then handles everything else — like spinning up Claude Code to fix issues for me.

Think of it as an AI assistant orchestrating another AI assistant. Pretty cool, right?

## Quick Start

### Docker (Recommended)

Pre-built images are published to GitHub Container Registry on every release.

```bash
docker pull ghcr.io/freema/openclaw-mcp:latest
```

Create a `docker-compose.yml`:

```yaml
services:
mcp-bridge:
image: ghcr.io/freema/openclaw-mcp:latest
container_name: openclaw-mcp
restart: unless-stopped
ports:
- "3000:3000"
environment:
- OPENCLAW_URL=http://host.docker.internal:18789
- OPENCLAW_GATEWAY_TOKEN=${OPENCLAW_GATEWAY_TOKEN}
- AUTH_ENABLED=true
- MCP_CLIENT_ID=openclaw
- MCP_CLIENT_SECRET=${MCP_CLIENT_SECRET}
- MCP_ISSUER_URL=${MCP_ISSUER_URL:-}
- CORS_ORIGINS=https://claude.ai
extra_hosts:
- "host.docker.internal:host-gateway"
read_only: true
security_opt:
- no-new-privileges
```

Generate secrets and start:

```bash
export MCP_CLIENT_SECRET=$(openssl rand -hex 32)
export OPENCLAW_GATEWAY_TOKEN=your-gateway-token
docker compose up -d
```

Then in Claude.ai add a custom MCP connector pointing to your server with `MCP_CLIENT_ID=openclaw` and your `MCP_CLIENT_SECRET`.

> **Tip:** Pin a specific version instead of `latest` for production: `ghcr.io/freema/openclaw-mcp:1.1.0`

### Local (Claude Desktop)

```bash
npx openclaw-mcp
```

Add to your Claude Desktop config:

```json
{
"mcpServers": {
"openclaw": {
"command": "npx",
"args": ["openclaw-mcp"],
"env": {
"OPENCLAW_URL": "http://127.0.0.1:18789",
"OPENCLAW_GATEWAY_TOKEN": "your-gateway-token",
"OPENCLAW_TIMEOUT_MS": "300000"
}
}
}
}
```

### Remote (Claude.ai) without Docker

```bash
AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=your-secret \
MCP_ISSUER_URL=https://mcp.your-domain.com \
CORS_ORIGINS=https://claude.ai OPENCLAW_GATEWAY_TOKEN=your-gateway-token \
npx openclaw-mcp --transport sse --port 3000
```

> **Important:** When running behind a reverse proxy (Caddy, nginx, etc.), you **must** set `MCP_ISSUER_URL` (or `--issuer-url`) to your public HTTPS URL. Without this, OAuth metadata will advertise `http://localhost:3000` and clients will fail to authenticate.

See [Installation Guide](docs/installation.md) for details.

## Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│ Your Server │
│ │
│ ┌─────────────────┐ ┌─────────────────────────┐ │
│ │ OpenClaw │ │ OpenClaw MCP │ │
│ │ Gateway │◄────►│ Bridge Server │ │
│ │ :18789 │ │ :3000 │ │
│ │ │ │ │ │
│ │ OpenAI-compat │ │ - OAuth 2.1 auth │ │
│ │ /v1/chat/... │ │ - CORS protection │ │
│ └─────────────────┘ │ - Input validation │ │
│ └──────────┬──────────────┘ │
│ │ │
└──────────────────────────────────────┼──────────────────────────┘
│ HTTPS + OAuth 2.1
▼
┌─────────────────┐
│ Claude.ai │
│ (MCP Client) │
└─────────────────┘
```

## Available Tools

### Sync Tools

| Tool | Description |
|------|-------------|
| `openclaw_chat` | Send messages to OpenClaw and get responses |
| `openclaw_status` | Check OpenClaw gateway health |

### Async Tools (for long-running operations)

| Tool | Description |
|------|-------------|
| `openclaw_chat_async` | Queue a message, get task_id immediately |
| `openclaw_task_status` | Check task progress and get results |
| `openclaw_task_list` | List all tasks with filtering |
| `openclaw_task_cancel` | Cancel a pending task |

## Documentation

- [Installation](docs/installation.md) — Setup for Claude Desktop & Claude.ai
- [Configuration](docs/configuration.md) — Environment variables & options
- [Deployment](docs/deployment.md) — Docker & production setup
- [Threat Model](docs/threat-model.md) — What Claude can/can't trigger, trust boundaries & attack surfaces
- [Logging](docs/logging.md) — What gets logged, where, and what is never logged
- [Development](docs/development.md) — Contributing & adding tools
- [Security](SECURITY.md) — Security policy & best practices

## Security

⚠️ **Always enable authentication in production!**

```bash
# Generate secure client secret
export MCP_CLIENT_SECRET=$(openssl rand -hex 32)

# Run with auth enabled
AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=$MCP_CLIENT_SECRET \
openclaw-mcp --transport sse
```

Configure CORS to restrict access:

```bash
CORS_ORIGINS=https://claude.ai,https://your-app.com
```

See [Configuration](docs/configuration.md) for all security options.

## Requirements

- Node.js ≥ 20
- OpenClaw gateway running with HTTP API enabled:
```json5
// openclaw.json
{ "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } }
```

## License

MIT

## Author

Created by [Tomáš Grasl](https://www.tomasgrasl.cz/)

## Related Projects

- [OpenClaw](https://github.com/openclaw/openclaw) — The AI assistant this MCP connects to
- [MCP Specification](https://spec.modelcontextprotocol.io/) — Model Context Protocol docs

ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/freema/openclaw-mcp

Awesome Lists containing this project

README