Openclaude MCP README

OpenClaude MCP Server

📖 Installation Guide — quick start, manual setup, and troubleshooting

A high-performance control plane for Ollama-based local LLM sessions, with background memory consolidation (KAIROS), hybrid cloud planning (ULTRAPLAN), and real-time fleet monitoring. Optimized for RTX 4090 environments.

Features

Background Memory (KAIROS): Auto-consolidates session data into MEMORY.md using asynchronous background cycles. Configurable poll interval and consolidation budget. State persists across restarts.
Session Management: Launch, prompt, monitor, and stop multiple OpenClaude subprocesses concurrently. Persistent across restarts with usage analytics (prompts, output chars, estimated tokens).
Multimodal Input: Send images (png, jpeg, webp, gif) alongside text instructions via the send_multimodal tool. Works with any vision-capable Ollama model.
Ollama Control Plane: Model management with VRAM/speed/context metadata, health checks, default persistence.
Hybrid Planning (ULTRAPLAN): Optional cloud Opus/Sonnet handoff for complex reasoning, local execution. Token cost tracking included.
Fleet Observability: React dashboard with real-time SSE push, xterm.js terminal, system log viewer, KAIROS status, interactive API playground.
Interactive Examples: Live "Run" buttons on every example — calls the real backend, shows response JSON with timing.
API Reference: Searchable documentation with parameter tables, return schemas, env vars, error codes for all 15 tools.
Safety Guardrails: Kid-safe mode with content filters, proactive privacy reminders, caregiver alerts (file + webhook).
Dual Transport: MCP SSE (Claude Desktop) + REST bridge (webapp/curl) on the same port.

Quick Start

powershell

git clone https://github.com/sandraschi/openclaude-mcp
cd openclaude-mcp
just

This opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start.

Manual Setup

If you don't have just installed: .\setup.ps1 .\start.ps1

SSE Endpoint: http://localhost:10932/sse
Fleet Dashboard: http://localhost:10933
API Events: http://localhost:10932/api/events (SSE push)
Health API: http://localhost:10932/api/health Or with Docker: docker compose up

Available Tools (15)

Tool	Action
`start_session`	Initialize a new Ollama session
`send_prompt`	Execute a prompt in an active session
`send_multimodal`	Send text + images to a session (png, jpeg, webp, gif)
`session_status`	Get output/status/usage/elapsed of a session
`list_sessions`	List all active sessions
`stop_session`	Stop and clean up a session
`kairos_enable`	Activate background memory consolidation
`kairos_disable`	Halt background memory consolidation
`kairos_log`	Retrieve KAIROS consolidation log
`list_models`	Inventory of available Ollama models
`set_default_model`	Set default model for new sessions
`model_status`	Check VRAM and load status
`ultraplan`	Hybrid cloud/local planning cycle
`fleet_dashboard`	Prefab UI fleet status overview
`fleet_status`	Raw fleet status JSON
`caregiver_alert`	[KID-SAFE] Notify caregivers of high-risk interaction

Architecture

Code

                    ┌─────────────────┐
                    │  Claude Desktop  │── SSE ──────┐
                    │  Cursor / VSCode │             │
                    └─────────────────┘             │
                                                    ▼
┌──────────────┐  REST  ┌────────────────────────────┐  stdio (NDJSON)  ┌──────────────────┐
│  React Webapp│───────►│  server.py (FastMCP 3.2)   │◄────────────────│  OpenClaude CLI   │
│  (SSE push)  │◄───────│  + SessionStore             │    subprocess    │  (Node.js/Bun)    │
└──────────────┘        │  + ModelRouter              │◄───────────────►│  + Ollama :11434  │
                        │  + KairosController         │                 └──────────────────┘
                        │  + SessionPersistence       │
                        │  + SSE Event Bus            │
                        └────────────────────────────┘

Configuration (env vars)

Variable	Default	Description
`OPENCLAUDE_MCP_PORT`	`10932`	Backend port
`OPENCLAUDE_MCP_TOKEN`	—	REST auth token (disable if unset)
`OPENCLAUDE_DIR`	`D:\Dev\repos\external\openclaude`	OpenClaude source path
`OPENCLAUDE_ULTRAPLAN_MODEL`	`claude-sonnet-4-6`	Anthropic model for ULTRAPLAN
`OPENCLAUDE_CONFIG_DIR`	`~/.config/openclaude`	Persistence directory
`KAIROS_POLL_SECONDS`	`30`	KAIROS daemon poll interval
`KAIROS_MAX_CONSOLIDATIONS`	`100`	Max consolidations per session
`CAREGIVER_WEBHOOK_URL`	—	Webhook for caregiver alerts

Prerequisites

Ollama (running locally)
Node.js (v20+)
Python 3.13+ with uv
Local model pulled (e.g., gemma4:26b, qwen3.5:35b-a3b)

Test Suite

powershell

uv run pytest                    # 79 tests (unit + smoke + integration + e2e)
uv run pytest tests/unit/        # fast, no external deps
uv run pytest tests/e2e/         # Anthropic API mocked via respx

License

MIT