Servidor MCP de OpenClaw

npm version License: MIT GHCR Website

🦞 Servidor del Protocolo de Contexto de Modelo (MCP) para la integración del asistente de IA OpenClaw.

Demo

Por qué construí esto

¡Hola! Creé este servidor MCP porque no quería depender únicamente de canales de mensajería para comunicarme con OpenClaw. Lo que realmente me entusiasma es la capacidad de conectar OpenClaw a la interfaz web de Claude. Básicamente, mi chat puede delegar tareas a mi bot Claw, que luego se encarga de todo lo demás, como iniciar Claude Code para solucionar problemas por mí.

Piensa en ello como un asistente de IA orquestando a otro asistente de IA. Bastante genial, ¿verdad?

Inicio rápido

Docker (Recomendado)

Las imágenes precompiladas se publican en el Registro de Contenedores de GitHub en cada lanzamiento.

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

Crea un docker-compose.yml:

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}
      - OPENCLAW_MODEL=openclaw
      - 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

Genera secretos e inicia:

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

Luego, en Claude.ai, añade un conector MCP personalizado que apunte a tu servidor con MCP_CLIENT_ID=openclaw y tu MCP_CLIENT_SECRET.

Consejo: Fija una versión específica en lugar de latest para producción: ghcr.io/freema/openclaw-mcp:1.1.0

Local (Claude Desktop)

npx openclaw-mcp

Añádelo a tu configuración de Claude Desktop:

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

Remoto (Claude.ai) sin Docker

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

Importante: Cuando se ejecuta detrás de un proxy inverso (Caddy, nginx, etc.), debes establecer MCP_ISSUER_URL (o --issuer-url) a tu URL HTTPS pública. Sin esto, los metadatos de OAuth anunciarán http://localhost:3000 y los clientes no podrán autenticarse.

Consulta la Guía de instalación para más detalles.

Arquitectura

┌─────────────────────────────────────────────────────────────────┐
│                         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)  │
                              └─────────────────┘

Herramientas disponibles

Herramientas de sincronización

Herramienta	Descripción
`openclaw_chat`	Enviar mensajes a OpenClaw y obtener respuestas
`openclaw_status`	Comprobar el estado de la pasarela de OpenClaw
`openclaw_instances`	Listar todas las instancias de OpenClaw configuradas

Herramientas asíncronas (para operaciones de larga duración)

Herramienta	Descripción
`openclaw_chat_async`	Poner un mensaje en cola, obtener task_id inmediatamente
`openclaw_task_status`	Comprobar el progreso de la tarea y obtener resultados
`openclaw_task_list`	Listar todas las tareas con filtrado
`openclaw_task_cancel`	Cancelar una tarea pendiente

Modo multi-instancia

Orquesta múltiples pasarelas de OpenClaw desde un único servidor MCP. Un puente, muchas garras: enruta las solicitudes a producción, staging, desarrollo o como quieras llamarlas (lobster-supreme y the-claw-abides son nombres perfectamente válidos).

┌──────────────────────────────────────────────────────────────────────┐
│                        Claude.ai / Claude Desktop                    │
│                              (MCP Client)                            │
└──────────────────────┬───────────────────────────────────────────────┘
                       │
                       ▼
┌──────────────────────────────────────────────────────────────────────┐
│                     OpenClaw MCP Bridge Server                        │
│                                                                      │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐               │
│  │  Instance     │  │  Instance     │  │  Instance     │              │
│  │  Registry     │  │  Resolver     │  │  Validator    │              │
│  └──────┬───────┘  └──────┬───────┘  └──────┬───────┘               │
│         │                 │                  │                        │
│  ┌──────┴─────────────────┴──────────────────┴───────┐               │
│  │              Per-Instance OpenClaw Clients          │              │
│  │     (separate auth, timeout, URL per instance)     │              │
│  └────────┬──────────────┬──────────────┬────────────┘               │
└───────────┼──────────────┼──────────────┼────────────────────────────┘
            │              │              │
            ▼              ▼              ▼
   ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
   │  🦞 prod     │ │  🦞 staging  │ │  🦞 dev      │
   │  (default)   │ │              │ │              │
   │  :18789      │ │  :18789      │ │  :18789      │
   │  OpenClaw GW │ │  OpenClaw GW │ │  OpenClaw GW │
   └──────────────┘ └──────────────┘ └──────────────┘

Configuración

OPENCLAW_INSTANCES='[
  {"name": "prod", "url": "http://prod:18789", "token": "tok1", "default": true},
  {"name": "staging", "url": "http://staging:18789", "token": "tok2"},
  {"name": "dev", "url": "http://dev:18789", "token": "tok3"}
]'

Uso

Todas las herramientas aceptan un parámetro opcional instance para dirigirse a una pasarela específica:

# Chat with staging instance
openclaw_chat message="Deploy status?" instance="staging"

# Check health of prod
openclaw_status instance="prod"

# List all configured instances
openclaw_instances

# Async task targeting dev
openclaw_chat_async message="Run tests" instance="dev"

Cuando se omite instance, se utiliza la instancia predeterminada. Cada instancia tiene su propio token de autenticación, tiempo de espera y URL: totalmente aisladas.

Características clave

Actualización sin migración — las implementaciones de instancia única existentes funcionan sin cambios en la configuración
Aislamiento por instancia — tokens de autenticación, tiempos de espera y URLs separados
Enrutamiento dinámico — Claude elige la instancia correcta por solicitud
Seguimiento de tareas — las tareas asíncronas recuerdan a qué instancia se dirigen
Seguridad — los tokens nunca se exponen a través de openclaw_instances

Consulta Configuración — Modo multi-instancia para la referencia completa.

Documentación

Instalación — Configuración para Claude Desktop y Claude.ai
Configuración — Variables de entorno y opciones
Despliegue — Docker y configuración de producción
Modelo de amenazas — Qué puede/no puede activar Claude, límites de confianza y superficies de ataque
Registro — Qué se registra, dónde y qué nunca se registra
Desarrollo — Contribución y adición de herramientas
Seguridad — Política de seguridad y mejores prácticas

Seguridad

⚠️ ¡Habilita siempre la autenticación en producción!

# 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

Configura CORS para restringir el acceso:

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

Consulta Configuración para todas las opciones de seguridad.

Requisitos

Node.js ≥ 20
Pasarela de OpenClaw ejecutándose con la API HTTP habilitada:

// openclaw.json
{ "gateway": { "http": { "endpoints": { "chatCompletions": { "enabled": true } } } } }

Licencia

MIT

Autor

Creado por Tomáš Grasl

Proyectos relacionados

OpenClaw — El asistente de IA al que se conecta este MCP
Especificación MCP — Documentación del Protocolo de Contexto de Modelo

openclaw-mcp