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

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

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

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