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.

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: localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for en, de, es, zh, ja, ru with English fallback
• 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.

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.