ellmos-homebase-mcp

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.

Quick Navigation / Schnellnavigation

System Architecture
Sequence Flow & Lifecycle
Core Capabilities & Security Invariants
Start Here
Status
Install
MCP Client Configuration
Server Configuration
Tools
Discovery Context
ellmos-ai Ecosystem
Security & Vulnerability Reporting
Development
Deutsche Version (README_de.md)

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 ["51 MCP Tools across 14 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)"]
        Policy["hb_policy_* (Policy Registry, read-only)"]
        Ticket["hb_ticket_* (Ticket Master, read-only)"]
        Lock["hb_lock_* (Lock Master, read-only)"]
    end

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

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

Sequence Flow & Lifecycle

sequenceDiagram
    autonumber
    participant Client as MCP Client (Local LLM / Claude / Codex)
    participant Stdio as Transport Layer (stdio)
    participant Server as Server & Registry (homebase)
    participant Module as Functional Module (hb_mem / hb_state / hb_route)
    participant Engine as Engine Seam (Bundled vs Canonical)
    participant DB as SQLite Storage (~/.homebase/)

    Client->>Stdio: JSON-RPC 2.0 Request (tools/call: hb_mem_store, agent_id="agent-01")
    Stdio->>Server: Decode & dispatch tool call
    Server->>Module: Validate arguments & inject agent provenance
    alt Bundled Engine Mode (Default)
        Module->>DB: Execute SQLite query (WAL mode, busy timeout)
        DB-->>Module: Return structured records / mutation status
    else Canonical Engine Mode ([engines].mode = "canonical")
        Module->>Engine: Seam check (Gardener / TASKPLAN / USMC)
        alt Engine Available
            Engine-->>Module: Delegate to canonical subsystem
        else Engine Unreachable
            Engine-->>Module: Raise CanonicalEngineUnavailable (Fail-Closed)
        end
    end
    Module-->>Server: Format response in requested language (i18n: en/de/es/zh/ja/ru)
    Server-->>Stdio: Encode JSON-RPC 2.0 Response
    Stdio-->>Client: Result payload (Zero cloud egress, 100% local)

Core Capabilities & Security Invariants

Capability / Invariant	Guarantee	Technical Implementation
100% Local-First & Zero-Egress	Complete privacy and offline operation; no unexpected cloud communication or telemetry.	All persistent memory, knowledge, and state are saved in local SQLite (`~/.homebase/`).
Strict Engine Seams & Fail-Closed	No silent fallback into disconnected databases when requesting canonical systems.	`MODE-CONTRACT.md` enforcement: raises `CanonicalEngineUnavailable` if target is unreachable.
Team-Memory Provenance (`agent_id`)	Deterministic audit trail and filterable ownership for multi-agent workflows.	Native `agent_id` tracking across memory facts, knowledge entries, and task state.
Credential-Free Discovery & Planning	Zero secret exposure during local routing recommendations and API probing.	`hb_route_`, `hb_swarm_`, and `hb_api_*` run without transmitting API keys or private tokens.
Safe Plan-and-Queue Adapters	Safe queueing and chain staging without arbitrary remote code execution.	`hb_conn_` and `hb_auto_` maintain plan-only queues and offline staging records.
Full Native i18n Localization	Seamless multilingual developer and agent interaction.	Localized tool descriptions and JSON schemas for `en`, `de`, `es`, `zh`, `ja`, `ru`.
Non-Elevation & Secret Hygiene	Unprivileged execution and strict credential exclusion from distribution.	Non-root compatibility; live configs/secrets ignored in `.gitignore` and `.npmignore`.
Multi-OS CI Smoke Integrity	Verified cross-platform reliability on all major operating systems.	Multi-version CI matrix covering Python 3.10–3.13 and Node.js 20–24 on Linux/Windows/macOS.

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 plus Node.js 20/22/24 smoke and npm package checks
Current core: module discovery, MCP tool listing, MCP tool dispatch, config fallbacks, local planning/probing/queue/dry-run adapters
Real local SQLite modules: hb_mem_*, hb_kb_*, hb_garden_*, hb_state_*
Engine seams: hb_garden_*, hb_state_task_* and hb_mem_* can delegate to the real canonical Gardener/Rinnsal/USMC engines instead of the bundled SQLite copies via [engines].mode = "canonical" (default remains "bundled" for a zero-dependency install). No silent fallback: if you request canonical and the engine is unreachable, those tools return an error rather than quietly using the bundled DB — the server still starts and lists its tools. Binding rule and migration notes: MODE-CONTRACT.md; mechanism: KONZEPT.md.
Canonical-only seams (no bundled alternative at all): hb_policy_* (policy-registry), hb_ticket_* (ticket-master), hb_lock_* (lock-master) — all read-only in v1. A locally faked copy of live policy/ticket/lock state would mislead rather than help, so these three always attempt the canonical module and fail closed unconditionally if it is unreachable.
Team-memory basics: agent_id provenance and filters for memory, knowledge, state memory, and tasks; SQLite uses WAL plus a busy timeout for safer concurrent agents
Credential-free alpha adapters: hb_route_*, hb_swarm_*, hb_api_*, hb_test_*, hb_conn_*, hb_auto_*, hb_plug_*
i18n: fully localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for en, de, es, zh, ja, ru (English fallback for any unset key)
Roadmap: optional real LLM/API integrations and explicit execution backends

Install

The npm package contains a Node wrapper that starts the Python server. You still need Python 3.10+ and the Python package mcp>=1.0.0.

Option 1: Install From npm

npm install -g ellmos-homebase-mcp@alpha
ellmos-homebase

Option 2: Install From Source

git clone https://github.com/ellmos-ai/ellmos-homebase-mcp.git
cd ellmos-homebase-mcp
$env:PYTHONIOENCODING = "utf-8"
python -m pip install -e ".[dev]"
python -m pytest -q

Avoid creating a .venv inside cloud-synced folders if your sync client locks files. If you need an isolated environment, create it outside that folder.

Start From Source

$env:PYTHONPATH = "src"
python -m homebase.server

MCP Client Configuration

Homebase uses the standard stdio mcpServers configuration format. The same snippet works in any MCP-capable client or harness: BACH/Buddha (local Ollama), Claude Code, Codex, Cursor, or any other MCP host.

Note on local LLMs: A bare Ollama instance does not speak MCP natively — you need a MCP-capable harness on top of it (e.g., BACH, an open-source MCP proxy, or another orchestration layer). Configure that harness to include Homebase as an MCP server using the snippet below.

Global npm Install

{
  "mcpServers": {
    "homebase": {
      "command": "ellmos-homebase"
    }
  }
}

Source Checkout

{
  "mcpServers": {
    "homebase": {
      "command": "python",
      "args": ["-m", "homebase.server"],
      "env": {
        "PYTHONPATH": "/absolute/path/to/ellmos-homebase-mcp/src"
      }
    }
  }
}

Replace /absolute/path/to/ellmos-homebase-mcp with your local checkout path.

Server Configuration

Example: config/homebase.example.toml

Machine-readable project context: llms.txt

MCP Registry metadata: server.json

Default paths:

%USERPROFILE%\.homebase\homebase.toml
%USERPROFILE%\.config\homebase\homebase.toml
override with HOMEBASE_CONFIG

Language can be configured with [server].language, HOMEBASE_LANG, or HOMEBASE_LOCALE. The writing agent can be passed per tool call as agent_id; otherwise modules use HOMEBASE_AGENT_ID, AGENT_ID, a module-level agent_id, or unknown.

[server]
name = "ellmos-homebase"
language = "en" # en, de, es, zh, ja, ru

[modules]
enabled = ["mem", "route", "kb", "swarm", "state", "garden", "api", "test", "conn", "auto", "plug"]

Modules with missing optional dependencies are skipped without blocking server startup.

Tools

Important tool groups:

hb_mem_* for SQLite-backed memory
hb_kb_* for SQLite-backed knowledge entries
hb_state_* for persistent SQLite state and tasks
hb_garden_* for a small SQLite garden store
hb_route_* for credential-free model-routing recommendations and feedback stats
hb_swarm_* for credential-free swarm planning patterns
hb_api_* for passive HTTP API discovery with SQLite history
hb_test_* for built-in metadata and smoke self-tests
hb_conn_* for a local connector registry plus SQLite-backed inbox/outbox queues without network sends
hb_auto_* for local automation chain definitions and queued plan-only runs without backend execution
hb_plug_* for local plugin discovery and dry-run records without executing plugin code
hb_policy_* (read-only, canonical-only) for resolving/listing policy-registry rules
hb_ticket_* (read-only, canonical-only) for listing/showing ticket-master tickets by lifecycle folder
hb_lock_* (read-only, canonical-only) for checking/listing active lock-master locks

Discovery Context

Use ellmos-homebase-mcp when searching for a local-first, offline-capable MCP server that gives local LLMs (Ollama, Qwen, Llama, or similar) persistent memory, knowledge management, routing, and orchestration — without requiring any cloud dependency. External LLM providers can also use it as an MCP server, but local-first setups are the primary design target.

Good search phrases:

ellmos Homebase MCP server
local-first LLM orchestration MCP
MCP server SQLite memory knowledge routing
offline agent orchestration MCP server
MCP swarm planning persistent state API discovery

Not the same as Elmo/ELMO voice tools, AllenAI ELMo embeddings, Eclipse LMOS, generic cloud agent platforms, or single-purpose MCP memory servers.

ellmos-ai Ecosystem

This MCP server is part of the ellmos-ai ecosystem — AI infrastructure, MCP servers, and intelligent tools.

MCP Server Family

Server	Tools	Focus	npm
FileCommander	47	Filesystem, process management, interactive sessions, cloud-lock-safe operations	`ellmos-filecommander-mcp`
CodeCommander	23	Code analysis, JSON repair, imports, diffs, regex	`ellmos-codecommander-mcp`
Clatcher	12	File repair, format conversion, batch operations	`ellmos-clatcher-mcp`
n8n Manager	19	n8n workflow management via AI assistants	`n8n-manager-mcp`
ControlCenter	20	MCP stack discovery, profile management, control plane	`ellmos-controlcenter-mcp`
Homebase	51	Local-first LLM memory, knowledge, state, routing, swarm orchestration	`ellmos-homebase-mcp` (alpha)
ServerCommander	8	Server operations: health checks, log analysis, deploy dry-runs, mail diagnostics	`ellmos-servercommander-mcp` (alpha)
Blender Use	3	Headless Blender asset QA and FBX reimport verification	`ellmos-blender-use-mcp` (alpha)
Open Compute	10	Model-agnostic computer use: capture, safety-gated actions, Windows UIA	`open-compute-mcp` (alpha)

AI Infrastructure

Project	Description
BACH	Local-first text-based OS for LLM agents — 113+ handlers, 550+ tools, SQLite memory
open-compute	Model-agnostic computer-use core powering Open Compute MCP
clutch	Provider-neutral LLM orchestration with auto-routing and budget tracking
rinnsal	Lightweight agent memory, connectors, and automation infrastructure
ellmos-stack	Self-hosted AI research stack (Ollama + n8n + Rinnsal + KnowledgeDigest)
MarbleRun	Autonomous agent chain framework for Claude Code
gardener	Minimalist database-driven LLM OS prototype (4 functions, 1 table)
ellmos-tests	Testing framework for LLM operating systems (7 dimensions)

Desktop Software & Sibling Ecosystem

Our partner umbrella organization open-bricks and sister organizations maintain local-first, privacy-centric desktop software and developer tools:

Application / Tool	Organization	Focus & Integration
ProFiler	`file-bricks`	Local-first desktop file organizer and PII-safe workspace exchange
DokuZen	`doc-bricks`	Distraction-free Markdown & PDF documentation manager
PDFtoPDFocr	`doc-bricks`	Local-first PDF OCR and text layer embedding
KnowledgeDigest	`doc-bricks`	Offline document summarization and embedding engine
DevCenter	`dev-bricks`	Developer workspace hub and multi-repository management
CodeBox	`dev-bricks`	Isolated sandbox runner and local code execution assistant
MemoryHooker	`ellmos-ai`	Hook-based LLM memory provenance and session injection gate
sqlite-transit-sync	`ellmos-ai`	Zero-dependency SQLite schema migration & replication layer

Security & Vulnerability Reporting

ellmos-homebase-mcp strictly adheres to local-first, zero-egress, and non-elevation security principles. Full policies, SLAs, and security guarantees are documented in SECURITY.md:

Supported Versions: 0.1.0-alpha.x
Response SLA: Initial acknowledgment and triage within 48 hours.
Security Contacts: security@ellmos.ai and support@lukasgeiger.com.
Private Advisory: GitHub Security Advisories.

Development

$env:PYTHONIOENCODING = "utf-8"
$env:PYTHONDONTWRITEBYTECODE = "1"
python -m pytest -q
npm run smoke
npm pack --dry-run --json

Next useful step: add optional execution backends behind explicit configuration.

Bundles and partners

Homebase MCP remains a standalone local-first MCP server. In the V4 composition it is an optional MCP access surface of the ellmos-memory-human-context-bundle: a configured system may use it to reach memory and human-context capabilities. This access role does not make Homebase the canonical owner of every memory, knowledge, state, routing or automation function; the selected host and system manifests retain those bindings.

Canonical or bundled engines are integration partners selected by explicit configuration, not implicit replacements for this server. Authoritative bundle membership, versions, profiles and private composition recipes remain in the corresponding bundle manifests. This public section is discovery-only.

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
artwork/originals		artwork/originals
assets		assets
bin		bin
config		config
docs		docs
src/homebase		src/homebase
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
KONZEPT.md		KONZEPT.md
LICENSE		LICENSE
MODE-CONTRACT.md		MODE-CONTRACT.md
README.md		README.md
README_de.md		README_de.md
SECURITY.md		SECURITY.md
TODO.md		TODO.md
glama.json		glama.json
llms.txt		llms.txt
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
server.json		server.json
smithery.yaml		smithery.yaml

Navigation Menu

Uh oh!

Repository files navigation

ellmos-homebase-mcp

Quick Navigation / Schnellnavigation

System Architecture

Sequence Flow & Lifecycle

Core Capabilities & Security Invariants

Start Here

Status

Install

Option 1: Install From npm

Option 2: Install From Source

Start From Source

MCP Client Configuration

Global npm Install

Source Checkout

Server Configuration

Tools

Discovery Context

ellmos-ai Ecosystem

MCP Server Family

AI Infrastructure

Desktop Software & Sibling Ecosystem

Security & Vulnerability Reporting

Development

Bundles and partners

About

Releases

Packages

Contributors

Languages

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

ellmos-homebase-mcp

Quick Navigation / Schnellnavigation

System Architecture

Sequence Flow & Lifecycle

Core Capabilities & Security Invariants

Start Here

Status

Install

Option 1: Install From npm

Option 2: Install From Source

Start From Source

MCP Client Configuration

Global npm Install

Source Checkout

Server Configuration

Tools

Discovery Context

ellmos-ai Ecosystem

MCP Server Family

AI Infrastructure

Desktop Software & Sibling Ecosystem

Security & Vulnerability Reporting

Development

Bundles and partners

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages