ellmos-homebase-mcp

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

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.

Status

Transport: stdio via the Python MCP SDK
Package status: public alpha package under ellmos-ai
Current core: module discovery, MCP tool listing, MCP tool dispatch, config fallbacks, local planning/probing adapters
Real local SQLite modules: hb_mem_*, hb_kb_*, hb_garden_*, hb_state_*
Credential-free alpha adapters: hb_route_*, hb_swarm_*, hb_api_*, hb_test_*
i18n: localized MCP tool descriptions, input-schema field descriptions, and unknown-tool errors for en, de, es, zh, ja, ru with English fallback
Roadmap: backend execution adapters for automation, connectors, plugins, and optional real LLM/API integrations

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

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

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.

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

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

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

Development

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

Next useful step: wire the remaining automation, connector, and plugin modules to credential-free local adapters, then add optional execution backends behind explicit configuration.

MCP Servers