← Back to Documentation

Home Assistant toolkit

Read selected Home Assistant entities and control explicitly allowed lights and switches.

Tool Reference: 4 tools with full schemas →

The Home Assistant toolkit connects devices already managed by Home Assistant to your AI assistant through Toolforest. It does not automatically expose an existing Apple Home configuration.

Setup

Install the latest published integration from GitHub releases through a HACS custom repository. The integration connects to the public Toolforest service.

Before you start

• A running Home Assistant instance and access to its configuration directory.
• Permission to install a custom integration and restart Home Assistant.
• A Toolforest account and a configured MCP client.

The integration runs inside Home Assistant. It makes an outbound secure WebSocket connection to Toolforest; you do not need Anki, AnkiConnect, a separate bridge service, a Home Assistant API token, or an inbound Internet endpoint.

1. Install the integration

1. In HACS, add https://github.com/Toolforest-io/toolforest-home-assistant as a custom repository of type Integration.
2. Download the latest published Home Assistant toolkit release, then restart Home Assistant.

For manual installation, download toolforest.zip from the release and extract it into <config>/custom_components/toolforest/, then restart Home Assistant. The resulting path must be <config>/custom_components/toolforest/manifest.json.

HACS installation of the published v0.1.0 release has been verified. Default-catalog inclusion is awaiting HACS maintainers; use the custom-repository path meanwhile. Do not install an Anki add-on or a Supervisor add-on for this toolkit.

2. Pair with Toolforest

1. In Home Assistant, open Settings → Devices & services → Add integration.
2. Search for Home Assistant toolkit.
3. Enter an Instance name you will recognise. If your installed version shows a Toolforest environment field, select Production.
4. Open the activation link shown by the integration. Sign in to your Toolforest account and approve the displayed device code.
5. Return to Home Assistant and submit the pairing form.

Pairing codes expire after ten minutes. If a code expires, start setup again. If Home Assistant says authorization is pending, approve the code in Toolforest, wait a few seconds, and submit again.

The instance name, instance ID, and connection status are supplied to the portal automatically after pairing. You do not need to enter them in the toolkit row.

3. Choose what your assistant can access

Nothing is exposed by default. In the Home Assistant setup form, select:

Selection	What it allows
Entities to expose for state reads	Discovery and current-state reads for selected lights and switches
Exposed entities allowed to turn on	Turning on those selected entities
Exposed entities allowed to turn off	Turning off those selected entities
Exposed lights allowed to change brightness	Brightness changes when turning on supported lights

Every action target must also be selected for state reads. Brightness requires a light that supports it. Selecting an entity for reads alone does not grant control. A selected Home Assistant group can affect multiple devices; choose individual entities if you want individual control.

Finish setup. To change permissions later, open Settings → Devices & services → Home Assistant toolkit → Configure. Saving options reloads the integration and applies the new permissions.

4. Check the connection

In Home Assistant, check the diagnostic Home Assistant toolkit connection sensor. In the Toolforest portal, select your MCP client and open Other. The Home Assistant toolkit row should show Connected.

Ask your assistant to use Toolforest to list your Home Assistant instances, list the exposed entities for the intended instance, and read a selected entity’s state. Only try a control after granting that action in Home Assistant.

Manage the connection

The toolkit toggle hides or enables tools for the selected MCP client while preserving pairing. Disconnect revokes a paired Home Assistant connection. Pair again through Home Assistant to restore a revoked connection.

Use ⋮ → Manage connections to inspect paired instances and disconnect a particular one. When several instances are paired, the row’s Disconnect button opens that dialog so you can choose the intended connection. Technical instance IDs are available under Technical details; they are not fields you need to fill in.

Every MCP request targets an explicit instance ID discovered through list_instances. Inspecting a connection in the portal does not change an assistant’s default target. Give your instances distinct names and ask your assistant to confirm the intended instance before controlling it.

Disabling and re-enabling the integration, or selecting Reload in its Home Assistant entry menu, restarts its connection without changing pairing. Removing the integration attempts to revoke the device remotely; if Toolforest cannot be reached, also disconnect it in the portal.

Troubleshooting

• Paired · Offline: pairing exists, but the integration is not currently connected. Check that Home Assistant and the integration are running and can make outbound secure WebSocket connections. The integration reconnects automatically after a network interruption.
• Status unavailable: the portal cannot check the connection. Restore browser connectivity and retry; this status does not mean pairing has been removed.
• Disconnected: no active pairing is visible to the signed-in account. Check that you are signed in to the account used for pairing, or pair again in Home Assistant.
• Attention required in Home Assistant: the connection credential was revoked or is invalid. Open the integration’s reconfiguration flow and pair again.
• No entities or an action denied: check the read and action selections in Home Assistant. Permissions and current capabilities are checked again when each request executes.
• A control times out or the connection drops: the result may be uncertain. Read the entity’s current state before deciding whether to repeat the action. Toolforest does not automatically replay uncertain writes after reconnecting.

Only selected lights and switches are supported in this MVP. Arbitrary services, network requests, locks, alarms, garage controls, cameras, climate controls, scenes, scripts, and event history are outside its scope. Direct Apple Home/HomeKit access and Matter-controller functionality are follow-ons.

Local verification

For a hardware-free Home Assistant setup using Docker or Colima and virtual entities, follow the integration repository’s local development instructions. Its verification record distinguishes real gateway/MCP checks from unit tests and unverified distribution methods.