ellmos-homebase-mcp

<p align="center"> <img src="assets/homebase-logo.jpg" alt="ellmos Homebase MCP logo" width="640"> </p>

Alpha MCP server for local-first LLM orchestration: memory, knowledge, routing, swarm patterns, API probing, persistent state, tests, automation planning, and plugin discovery in one stdio server.

Homebase is designed primarily for local LLMs (Ollama, Qwen, Llama, or any locally-hosted model via a MCP-capable harness). All persistent storage uses SQLite with no cloud dependency. External LLM providers (Claude, Codex, Gemini, OpenAI) can also connect as MCP clients, but local, offline-capable setups are the primary target.

German README: README_de.md

Part of the ellmos-ai family.

Discoverability: Published on npm as ellmos-homebase-mcp and maintained in the ellmos-ai organization.

[!NOTE] For AI Assistants & LLM Agents: Machine-readable architecture summary, index, and tool capabilities are published in llms.txt. MCP registry metadata is available in server.json.

System Architecture

flowchart TD
    subgraph Clients ["MCP Clients (Local / Remote)"]
        Ollama["Local LLMs (Ollama, Qwen, Llama)"]
        Claude["Claude Code / Desktop"]
        Codex["Codex / Antigravity"]
    end

    subgraph Transport ["Transport Layer"]
        Stdio["stdio (Python MCP SDK)"]
    end

    subgraph Core ["ellmos-homebase-mcp Core Engine"]
        Server["homebase.server"]
        Config["homebase.config"]
    end

    subgraph ToolGroups ["45 MCP Tools across 11 Functional Modules"]
        Mem["hb_mem_* (SQLite Memory)"]
        KB["hb_kb_* (Knowledge Digest)"]
        State["hb_state_* (State & Tasks)"]
        Route["hb_route_* (Model Router)"]
        Swarm["hb_swarm_* (Swarm Patterns)"]
        Api["hb_api_* (API Probing)"]
        Conn["hb_conn_* (Connectors Queue)"]
        Auto["hb_auto_* (Automation Chains)"]
        Plug["hb_plug_* (Plugin Discovery)"]
        Garden["hb_garden_* (Garden Store)"]
        Test["hb_test_* (Self Tests)"]
    end

    subgraph Storage ["Local Storage (Offline-First)"]
        DB[(SQLite Storage ~/.homebase/)]
    end

    Clients --> Stdio
    Stdio --> Server
    Server --> Config
    Server --> ToolGroups
    ToolGroups --> DB

Start Here

Need	Entry point
Install the alpha MCP server	npm install -g ellmos-homebase-mcp@alpha
Run from a source checkout	python -m homebase.server with PYTHONPATH=src
Configure a local LLM harness, Claude Code, Codex, or any MCP client	MCP Client Configuration
Inspect the machine-readable project summary	llms.txt
Check registry metadata	server.json

Status

• Transport: stdio via the Python MCP SDK
• Package status: public alpha package under ellmos-ai
• Release metadata: MIT LICENSE, CHANGELOG.md, llms.txt, and MCP Registry metadata in server.json
• Test gate: GitHub Actions covers Python 3.10/3.11/3.12