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)

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)

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