openclaw-mcp 1.0.0

package/README.md

@@ -0,0 +1,140 @@
+# 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)
+
+🦞 Model Context Protocol (MCP) server for [OpenClaw](https://github.com/openclaw/openclaw) AI assistant integration.
+
+## 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
+
+### 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"
+      }
+    }
+  }
+}
+```
+
+### Remote (Claude.ai)
+
+```bash
+AUTH_ENABLED=true MCP_CLIENT_ID=openclaw MCP_CLIENT_SECRET=your-secret \
+  CORS_ORIGINS=https://claude.ai OPENCLAW_GATEWAY_TOKEN=your-gateway-token \
+  npx openclaw-mcp --transport sse --port 3000
+```
+
+Then in Claude.ai add a custom connector with your `MCP_CLIENT_ID` and `MCP_CLIENT_SECRET`.
+
+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
+- [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
+
+## 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