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 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_* and hb_state_task_* can delegate to the real canonical Gardener/Rinnsal engines instead of the bundled SQLite copies via [engines].mode = "canonical" (default remains "bundled" for a zero-dependency install). See KONZEPT.md.
• 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

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	46	Filesystem, process management, interactive sessions, cloud-lock-safe operations	ellmos-filecommander-mcp
CodeCommander	22	Code analysis, JSON repair, imports, diffs, regex	ellmos-codecommander-mcp
Clatcher	12	File repair, format conversion, batch operations	ellmos-clatcher-mcp
n8n Manager	18	n8n workflow management via AI assistants	n8n-manager-mcp
ControlCenter	20	MCP stack discovery, profile management, control plane	ellmos-controlcenter-mcp
Homebase	45	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

Our partner organization open-bricks bundles AI-native desktop applications — a modern, open-source software suite built for the age of AI. Categories include file management, document tools, developer utilities, and more.

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.