Samuel — Home Intelligence MCP Server

Samuel is an MCP server and bridge that gives Claude live access to the Example Home HA config and state. It runs on a dedicated Linux box (samuel) alongside a read-only clone of ha-config.

Note: This is a sanitized copy of a live deployment. Personal identifiers, device IDs, and network details have been replaced with placeholders. To use it, substitute your own HA host, token, and entity IDs.

Built for Home Assistant; not affiliated with or endorsed by the Home Assistant project or Open Home Foundation.

Relationship to Home Assistant

Samuel is designed to operate alongside an existing Home Assistant deployment.

This repository contains the Samuel MCP server and REST bridge:

• MCP server (port 5100) — tool-calling surface for Claude; implements Config, State, Doc, and Health tool groups
• REST bridge (port 5101) — HTTP interface for non-MCP callers and health checks

Samuel does not directly control devices. All execution occurs through Home Assistant, and all proposed actions require explicit human confirmation.

A complete deployment includes:

• A Home Assistant configuration repo with Samuel integration
• This Samuel service repo running alongside HA

See the Home Assistant configuration here:

• ha-config-public

This separation is intentional:

• Home Assistant remains deterministic and authoritative
• Samuel remains advisory, inspectable, and constrained

Quick Start

# On the Samuel box (Ubuntu Server):
cd ~/samuel-system
bash install.sh

The install script will:

1. Find Python 3.10+ (required by the MCP SDK)
2. Create a virtual environment at .venv
3. Install dependencies
4. Create ~/data/ for state persistence
5. Optionally install systemd services (auto-start on boot)

Prerequisites

1. Clone this repo: git clone git@github.com:your-github-user/samuel-system.git ~/samuel-system
2. Clone ha-config (read-only): git clone git@github.com:your-github-user/ha-config.git ~/ha-config
3. Create .env from the example: cp .env.example .env and fill in values

Environment Variables

Variable	Required	Description
HA_URL	Yes	Home Assistant URL (e.g. http://YOUR_HA_HOST:8123)
HA_TOKEN	Yes	HA long-lived access token
REPO_PATH	Yes	Path to ha-config clone (e.g. /home/samuel/ha-config)
DATA_DIR	No	State persistence directory (default: ~/data)
SAMUEL_PORT	No	MCP server port (default: 5100)
BRIDGE_PORT	No	Bridge server port (default: 5101)
SAMUEL_BRIDGE_URL	No	Bridge base URL used by comms tools (default: http://127.0.0.1:5101)
TELEGRAM_BOT_TOKEN	No	Telegram bot token — enables send_message_to_operator
TELEGRAM_CHAT_ID	No	Telegram chat ID for outbound operator messages

Manual Run

source .venv/bin/activate
python -m samuel          # MCP server (port 5100)
python -m samuel.bridge   # Bridge server (port 5101)

Connect Claude Code

claude mcp add --transport http samuel http://samuel.local:5100/mcp

Connect Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "samuel": {
      "url": "http://samuel.local:5100/mcp"
    }
  }
}

Available Tools

Tools are organized by domain. Each tool is registered with risk metadata (via tool_metadata.py) so Samuel can make safe autonomous decisions about what to call without approval.

Config Tools — config_tools.py (read from ha-config repo)

Tool	Risk	What It Does
read_config	read_only	Read any YAML config file
list_packages	read_only	List all packages with contents summary
list_automations	read_only	List all automations with triggers
list_scripts	read_only	List all scripts with actions
search_config	read_only	Regex search across all config files

State Tools — state_tools.py (query HA API)

Tool	Risk	What It Does
get_entity_state	read_only	Get entity state (supports fuzzy search)
get_entities_by_domain	read_only	List all entities for a domain
get_area_state	read_only	Get all entity states for a room/area

Doc Tools — doc_tools.py

Tool	Risk	What It Does
read_doc	read_only	Read any doc from docs/
get_system_map	read_only	Shortcut for the full system map

Health Tools — health_tools.py

Tool	Risk	What It Does
generate_health_report	read_only	Run health diagnostic with trend tracking

Briefing Tools — briefing_tools.py

Tool	Risk	What It Does
generate_status_briefing	read_only	Build a spoken home status summary (mode, presence, lights, temp, weather)

Home Infrastructure Tools — home_infra_tools.py

Requires home_assistant_bridge, host_bridge, and event_pipeline modules (not in public repo — see comments in the file for the interface contract).

Tool	Risk	What It Does
get_system_info	read_only	HA version, OS, hostname, hardware
get_system_health	read_only	HA component health status
list_entities	read_only	All entities, filterable by domain
get_entity_history	read_only	State history for an entity (up to 30 days)
get_cache_stats	read_only	In-process entity state cache statistics
get_automations	read_only	All automations with id and enabled state
get_automation	read_only	Full config for a single automation
validate_automations	read_only	Run HA config validation
list_services	read_only	Available HA services by domain
call_service	high_risk	Call a HA service — requires approved=True
get_recent_events	read_only	Recent events from HA WebSocket shadow pipeline
start_event_shadow_pipeline	low_risk	Start HA WebSocket event stream
stop_event_shadow_pipeline	low_risk	Stop HA WebSocket event stream
get_recent_logs	read_only	Recent HA log entries, filterable by level
search_logs	read_only	Full-text search across recent HA logs
get_failed_automations	read_only	Automations that have errored recently
get_integration_status	read_only	Integration health (loaded vs. failing)
get_host_info	read_only	Host OS info (kernel, distro, uptime)
get_system_metrics	read_only	Real-time CPU, memory, load
check_network	read_only	Network reachability check
check_disk_health	read_only	Disk usage and SMART health
get_vm_state	read_only	State of hosted VMs (e.g. HA OS VM)
restart_vm	high_risk	Restart a VM — requires approved=True

Comms Tools — comms_tools.py

Tool	Risk	What It Does
send_message_to_operator	moderate_risk	Send a message via Telegram (substance required — empty greetings are blocked)
request_approval	low_risk	Send an approval request with Approve/Deny buttons via HA mobile notification
poll_approval_response	read_only	Check status of a pending approval request

Tool Metadata — tool_metadata.py

Tool	Risk	What It Does
list_tool_metadata_json	read_only	Return full tool risk catalog as JSON
get_tool_metadata	read_only	Look up risk metadata for a specific tool

Service Management (systemd)

sudo systemctl status samuel-mcp       # Check status
sudo systemctl status samuel-bridge
sudo systemctl restart samuel-mcp      # Restart
sudo systemctl restart samuel-bridge
journalctl -u samuel-mcp -f            # Follow logs
journalctl -u samuel-bridge -f

Standalone Health Report

The diagnostics/morning_health.py script can run independently (e.g. via cron):

source .venv/bin/activate
python diagnostics/morning_health.py --dry-run   # Preview
python diagnostics/morning_health.py              # Write to DATA_DIR

Testing

# Start samuel, then in another terminal:
npx @modelcontextprotocol/inspector
# Connect to http://localhost:5100/mcp
# Try calling list_packages, search_config("quiet_hours"), etc.

# Test bridge:
curl http://localhost:5101/ping
curl http://localhost:5101/health

Architecture

samuel-system (this repo)           ha-config (separate repo, read-only clone)
├── samuel/                         ├── packages/*.yaml
│   ├── server.py     (MCP :5100)  ├── scripts.yaml
│   ├── bridge.py     (REST :5101) ├── docs/system_map.md
│   ├── config_reader.py ────────→ └── ...
│   ├── ha_client.py ─────────────→ Home Assistant REST API
│   └── tools/
│       ├── config_tools.py         (reads ha-config YAML)
│       ├── state_tools.py          (queries HA /api/states)
│       ├── doc_tools.py            (reads docs/)
│       ├── health_tools.py         (HA + Samuel diagnostics)
│       ├── briefing_tools.py       (spoken home status summaries)
│       ├── home_infra_tools.py     (entity history, services, logs, host)
│       ├── comms_tools.py          (Telegram + approval request routing)
│       └── tool_metadata.py        (risk registry for all tools)
├── diagnostics/
├── systemd/
│   ├── samuel-mcp.service
│   └── samuel-bridge.service
└── .env

Risk model: every tool is registered with a risk level (read_only, low_risk, moderate_risk, high_risk), whether it requires explicit approval, and whether it's safe to call autonomously. Query the catalog at runtime via list_tool_metadata_json.

Related

• ha-config-public — The Home Assistant configuration that Samuel reads. Modular packages, lighting standards, motion-aware rooms, and presence detection.
• stewardship-layer — The governance framework Samuel implements for approval-gated execution: Propose → Explain → Confirm → Execute → Learn.

Requirements

• Python 3.10+
• Ubuntu Server 24.04 LTS (or similar Linux with systemd)
• .env with HA_URL, HA_TOKEN, and REPO_PATH
• Network access to HA instance (for state/health tools)
• Local clone of ha-config (for config/doc tools)