Hamster MCP

Full AI debugging and maintenance access to your Home Assistant.

What Can It Do?

Hamster MCP connects AI assistants — like Claude, ChatGPT, Cursor, and
others — to your Home Assistant instance. It's built for debugging and
maintenance — the kind of access you need when something isn't working
or you want to understand what's going on inside your system.

• Debug voice assistants — "Show me the last 5 voice pipeline runs
  and why speech-to-text failed"
• Inspect Matter networks — "What Matter nodes are in my network
  and are any unreachable?"
• Review system health — "List all repairs and diagnostics for my
  system"
• Debug automations — "Show me the trace for the last time the
  motion automation ran"
• Check logs — "Show me the Supervisor logs from the last hour" or
  "Are there any errors in the Home Assistant core log?"
• Audit entity exposure — "Which entities are exposed to Alexa
  but not to Google Assistant?"
• Manage Bluetooth — "What Bluetooth scanners are active and what
  are their connection stats?"

It also handles everyday tasks — turning on lights, listing automations,
checking entity states — but that's not its focus.

How It Works

Hamster MCP runs inside your Home Assistant as a custom integration. It
exposes HA's capabilities through three source groups:

• Services — all HA service actions (lights, climate, automations,
  scripts, etc.), with full field descriptions and selector metadata
• WebSocket commands (~200 commands) — entity/device/area
  registries, history, system log, config entries, diagnostics, repairs,
  Matter, Assist Pipeline, voice/conversation, Cloud/Nabu Casa, auth
  management, trace debugging, HACS, and more
• Supervisor (HA OS only) — Core/Supervisor/host logs, add-on
  management, backups, host and network info

Your AI assistant discovers what's available through 6 meta-tools:

When you add a new integration, any WebSocket commands or services it
registers are available to the AI immediately — no MCP server update
needed. The tradeoff: the first interaction in a conversation may take a
moment while the AI explores what's available.

How It Compares

There are several MCP servers for Home Assistant. Here's how Hamster
fits in:

ha-mcp (2k+ stars)
is the most popular, with 92 curated tools covering everyday control,
automation management, dashboards, HACS, and more. Its ha_call_service
tool is fully generic — it can call any HA service, including those from
custom integrations. For everyday use it's excellent. However, its other
90 tools only wrap a subset of HA's WebSocket commands. Entire
subsystems have no coverage:

• Matter (commissioning, node diagnostics, thread/wifi credentials)
• Assist Pipeline (create/manage/run/debug voice pipelines)
• Voice/Conversation (agent listing, sentence management, debug scoring)
• Cloud/Nabu Casa (subscription, remote connect/disconnect, Alexa/Google
  entity management)
• Auth management (list/create/delete users, change passwords)
• Trace debugging (set breakpoints, step through automations)
• Diagnostics and Repairs
• Bluetooth scanner management
• Shopping list, application credentials, webhooks, network config
• validate_config, fire_event, extract_from_target,
  get_triggers_for_target

home-assistant-vibecode-agent
(500+ stars) is focused on IDE-based development — editing HA
configuration files, managing HACS packages, creating dashboards from
Cursor or VS Code. It's a two-part architecture (HA add-on + local MCP
client) with git-based versioning and rollback.

hass-mcp (280+ stars) is
intentionally lean — REST-only, no WebSocket or Supervisor access, with
guided prompts for automation creation.

hass-mcp-server
(23 stars) is also a custom component like Hamster, but with hardcoded
tools and OAuth 2.0 support for use with Claude in the browser.

mcp-server-home-assistant
(archived) is being upstreamed into Home Assistant Core itself — official
first-party MCP support is coming.

Hamster's position: full dynamic access to all ~200 WebSocket
commands, every service, and the Supervisor, through 6 meta-tools.
Runs inside HA as a custom component with native auth. Designed for
debugging and maintenance rather than everyday device control.

What You Need

• Home Assistant 2025.2 or later
• HACS (for the recommended install method)
• An AI tool that supports MCP — see Connecting Your AI
  Tool for compatible clients and setup
  links

Installation

HACS (Recommended)

1. Open HACS → Integrations → three-dot menu → Custom repositories.
2. Add https://github.com/altendky/hamster-mcp with category
   Integration.
3. Search for Hamster MCP in HACS and install it.
4. Restart Home Assistant.
5. Go to
   Settings → Devices & Services
   → Add Integration → Hamster MCP.

Manual

1. Copy the custom_components/hamster_mcp directory into your Home
   Assistant config/custom_components/ directory.
2. Restart Home Assistant.
3. Go to
   Settings → Devices & Services
   → Add Integration → Hamster MCP.

Connecting Your AI Tool

Once the integration is running, point your AI tool at your Home
Assistant instance:

• URL: https://<your-ha-host>:<port>/api/hamster_mcp
  (e.g., http://homeassistant.local:8123/api/hamster_mcp)
• Transport: Streamable HTTP

Network access

The MCP endpoint is served by Home Assistant itself, so it's reachable
wherever your HA instance is.

• Local AI tools (Claude Desktop, Cursor, etc.) work as long as
  they're on the same network as your HA instance.
• Cloud AI tools (Claude.ai, ChatGPT, etc.) need your HA instance
  to be accessible from the internet — through
  Nabu Casa,
  a reverse proxy, or similar.

Authentication

Some AI tools will prompt you to log in through Home Assistant
automatically — just follow the login screen when it appears. Others
need a static token: create a
Long-Lived Access Token
in your HA profile (under Security) and provide it as a Bearer token in
your AI tool's configuration. Treat this token like a password — don't
share it or commit it to version control.

Compatible clients

These AI tools are known to work with Hamster MCP. Follow the setup
links for instructions on adding an MCP server in each tool:

Any MCP client that supports Streamable HTTP transport should work.
See the full client list on
the MCP website.

Try It Out

After connecting, try asking your AI assistant:

• "Show me the last 5 voice pipeline runs and their results."
• "Are there any system repairs I should look at?"
• "Show me which automations reference the front door sensor and their most recent traces."

If you get a useful answer, everything is working.

Status

Hamster MCP is in early release — functional and actively developed.
Feedback and bug reports are welcome via
GitHub Issues.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.