home_mcp_gateway

home_mcp_gateway is a local HTTP/SSE MCP gateway for ZeroClaw and other MCP clients. It centralizes tool calls, policy checks, artifact storage, jobs, and audit records behind one local MCP endpoint.

Manage settings, agents and LLM providers/models in the WebUI. Management data is stored in SQLite (default: artifacts/metadata.sqlite3). The first startup imports existing YAML and remote image settings; YAML remains the bootstrap configuration source.

Quick Start

Requirements:

• Docker with Docker Compose

• PowerShell on Windows for the helper scripts

Edit config/config.yaml and set at least callers.host_assistant.token, callers.role_default.token, and artifacts.signed_url_secret.

Build and run with Docker Compose:

$env:HOME_MCP_LOGIN_KEY = "your-login-key"
docker compose up -d --build

The default endpoint is http://127.0.0.1:8787.

Log in to the WebUI with HOME_MCP_LOGIN_KEY, independent of MCP caller tokens. Compose also accepts this variable from .env. In LLM Management, configure an OpenAI-compatible provider URL and API key, fetch models, select models to add, and assign text / image tags. URLs with /v1 are accepted. Remote Image selects an added model tagged image.

Check health:

Invoke-RestMethod http://127.0.0.1:8787/healthz
Invoke-RestMethod http://127.0.0.1:8787/readyz

Related MCP server: jgkme/kilo-image-gen-mcp

MCP Client

Use the SSE transport URL:

[[mcp.servers]]
name = "home"
transport = "sse"
url = "http://127.0.0.1:8787/mcp"
deferred_loading = true

When another Docker Compose service connects to this gateway on the same Docker network, use:

[[mcp.servers]]
name = "home"
transport = "sse"
url = "http://home-mcp:8787/mcp"
deferred_loading = true

Local Python Development

python -m pip install -e .
$env:HOME_MCP_DEV_MODE = "true"
python -m app.main

HOME_MCP_DEV_MODE=true opens management without login. MCP caller authentication and policy still apply. Use HOME_MCP_LOGIN_KEY with dev mode off for normal operation. Quotas, windows, concurrency, policy, artifacts, agents and tool parameters apply immediately on save. Only module switches require a restart.

The Settings page manages image/TTS/print quotas, counting windows, concurrency, artifact expiry and MCP access policy. The default image window is 86400 seconds (24 hours); both quota and window are editable. Zero quota/concurrency values mean unlimited. Module pages expose Parameters & limits for image editing/downloads, ComfyUI presets, voice options and print defaults. Running jobs keep their original settings, and in-memory quota counters reset on restart.

The default path is Docker Compose. Use local Python runs for development only.

Agents

Manage agents in the WebUI; caller and Matrix tokens are saved to SQLite. After migration, YAML edits do not override saved management data. Back up the database together with artifacts.

Tests

.\tests\run_tests.ps1

Documentation

• Documentation index: docs/README.md

• User guide: docs/user/README.md

• Current developer docs: docs/developer/README.md

• Original development docs: docs/original/README.md

• Chinese quick start: README.zh-cn.md