What openclaude-mcp does
openclaude-mcp provides an MCP control plane for OpenClaude sessions backed by Ollama. It can create sessions, send prompts, inspect progress and usage, enumerate active sessions, and stop sessions when they are no longer needed. Multiple sessions can run concurrently, with persistence and usage analytics for prompts, output characters, estimated tokens, and elapsed time.
The server also exposes controls for Ollama models and optional supporting services. Agents can list available models, choose the default model for new sessions, and inspect VRAM and load status. Image input is supported through a separate multimodal tool for PNG, JPEG, WebP, and GIF files when the selected Ollama model supports vision.
KAIROS provides asynchronous background memory consolidation into MEMORY.md, with state retained across restarts. ULTRAPLAN supports a hybrid planning flow that can hand complex reasoning to a cloud Opus or Sonnet model while leaving execution local. Fleet tools expose either a dashboard-oriented view or raw status data, and the caregiver alert tool can notify caregivers about high-risk interactions.
How it works
A FastMCP 3.2 Python server coordinates the sessions, model routing, persistence, KAIROS controller, and event bus. It launches the OpenClaude CLI as a subprocess and communicates with it over stdio using newline-delimited JSON. The CLI uses Ollama on its local service at port 11434.
MCP clients connect through the server's SSE endpoint at http://localhost:10932/sse. The same backend also exposes a REST bridge for the React web application and command-line requests. Server-sent events provide real-time updates to the web interface, which includes fleet status, terminal output, system logs, KAIROS state, and an API playground.
The default backend port is 10932, while the fleet dashboard is served at port 10933. Health information is available at /api/health, and event updates are available at /api/events.
Setup and configuration
The documented quick-start path is to clone the repository, enter its directory, and run just. just bootstrap installs dependencies; just serve or just dev starts the service. A PowerShell setup path is also available with setup.ps1 followed by start.ps1, and Docker Compose can start the stack with docker compose up.
The runtime requires Ollama running locally, Node.js 20 or newer, Python 3.13 or newer with uv, and at least one downloaded local model. Examples include gemma4:26b and qwen3.5:35b-a3b.
Configuration includes OPENCLAUDE_MCP_PORT for the backend port, OPENCLAUDE_MCP_TOKEN for optional REST authentication, OPENCLAUDE_DIR for the OpenClaude source location, and OPENCLAUDE_CONFIG_DIR for persistent data. OPENCLAUDE_ULTRAPLAN_MODEL selects the Anthropic model used by ULTRAPLAN. KAIROS polling and consolidation limits can be adjusted with KAIROS_POLL_SECONDS and KAIROS_MAX_CONSOLIDATIONS; CAREGIVER_WEBHOOK_URL configures webhook delivery for caregiver alerts.
Tools and capabilities
The MCP interface contains tools for the following operations:
- Create, prompt, inspect, list, and stop Ollama-backed sessions.
- Send text together with supported image formats through
send_multimodal.
- Enable, disable, and inspect the KAIROS consolidation log.
- List Ollama models, set the default model, and inspect model status.
- Run a ULTRAPLAN hybrid planning cycle.
- View a prepared fleet dashboard or retrieve raw fleet status JSON.
- Send a caregiver alert for a high-risk interaction.
The web application adds real-time SSE updates, an xterm.js terminal, system log viewing, KAIROS status, and interactive API examples that call the backend and display response timing.
Limitations and notes
Local operation depends on Ollama, the OpenClaude CLI, and a compatible model being available. Multimodal requests require a vision-capable Ollama model. ULTRAPLAN can use a cloud Opus or Sonnet handoff, so it is distinct from an entirely local session. REST authentication is configured separately through OPENCLAUDE_MCP_TOKEN and is disabled when that variable is unset. The project is licensed under MIT.