Model Context Protocol Server

The Model Context Protocol Server (MCP) integration lets you connect an AI agent, such as ChatGPT or Claude, to Home Assistant. The AI agent can then control your devices and see the current state of your home.

Prerequisites

• Your MCP server URL. To get it:
  1. Go to Settings > System > AI.
  2. If MCP is not enabled, enable it.
  3. Next to the MCP server you want to use, select the copy icon . We recommend My MCP because it lets the AI agent control everything Home Assistant has access to.
• An AI agent that supports MCP servers.
• If the AI agent runs in the cloud, for example when you use it through a website, your Home Assistant instance must be accessible from the internet. Use Home Assistant Cloud or another method of remote access.

For detailed configuration instructions, refer to the Client configuration section.

Configuration

To add the Model Context Protocol Server service to your Home Assistant instance, use this My button:

When you set up the integration, it exposes all LLM APIs and requires an administrator account. To change this, go to Settings > Devices & services, select Model Context Protocol Server, and then select Configure.

Configuration options

The integration provides the following configuration options:

Client configuration

Home Assistant implements the standard Model Context Protocol, including OAuth 2.0 with PKCE. It supports OAuth Client ID Metadata Documents, so AI agents set up the client ID and callback URL automatically.

Example: Claude

Before you start, copy your MCP server URL as described in the prerequisites.

1. Open the form to add a connector:

   • On claude.ai, go to the Claude connectors page. In the top-right corner, select Add > Add custom connector.
   • In Claude Desktop, go to Settings > Connectors and select Add > Add custom connector.

2. Enter the following details:

   • Name: Home Assistant
   • MCP Server URL: Paste your MCP server URL.

3. Select Add.

4. Claude verifies the MCP server and shows a dialog. Enter the following details:

   • Authentication: Select Sign in now.
   • OAuth client: Select Use Claude’s published identity.

5. Select Add.

6. On the page for your new connector, select Connect.

7. Log in to your Home Assistant instance.

8. You can now enable tools from Home Assistant when chatting with Claude, allowing you to control Home Assistant in a similar way to how you control it through the Voice Assistant. Claude will ask you for permission before calling any tools.

   

Example: ChatGPT

Before you start, copy your MCP server URL as described in the prerequisites.

1. Open the form to add an MCP server:
   • On chatgpt.com, go to the ChatGPT plugins page. In the top-right corner, select Add > Add custom MCP server.
   • In ChatGPT Desktop, go to Settings > Plugins and select Add > Add MCP server.
2. Enter the following details:
   • Name: Home Assistant
   • Connection: Paste your MCP server URL.
   • Authentication: Select OAuth.
3. Select I understand and want to continue.
4. Select Create as plugin.
5. ChatGPT offers to Connect Home Assistant. Select Continue to Home Assistant.
6. Log in to your Home Assistant instance.

Example: Claude Code

Claude Code connects to MCP servers over HTTPS only. Use the MCP server URL of your remotely accessible Home Assistant instance, as described in the prerequisites.

1. Install Claude Code and log in.

2. In your terminal, run the following command. Replace <your_mcp_server_url> with your MCP server URL.

   claude mcp add home-assistant --transport http <your_mcp_server_url>
   

3. Start claude and type /mcp.

4. Select home-assistant.

5. Select Authenticate.

6. Log in to your Home Assistant instance.

7. You can now enable tools from Home Assistant when chatting with Claude, allowing you to control Home Assistant in a similar way to how you control it through the Voice Assistant. Claude will ask you for permission before calling any tools.

Example: Codex

1. Install Codex and sign in.

2. In your terminal, run the following command. Replace <your_mcp_server_url> with your MCP server URL, for example http://homeassistant.local:8123/api/mcp.

   codex mcp add homeassistant --url <your_mcp_server_url>
   

3. Codex opens your Home Assistant instance in your web browser. Log in to your Home Assistant instance.

Example: OpenCode

OpenCode can connect to Home Assistant as a remote MCP server by using OAuth. This example uses the configuration format of OpenCode v2.

1. Install OpenCode.

2. Edit or create your configuration file:

   • To make the server available in every project, edit ~/.config/opencode/opencode.jsonc.
   • To use the server in one project only, edit opencode.jsonc in your project.

3. Add the following to your configuration:

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "servers": {
         "homeassistant": {
           "type": "remote",
           "url": "<your_home_assistant_url>/api/mcp",
           "oauth": {
             "client_id": "http://127.0.0.1:12345",
             "callback_port": 12345
           }
         }
       }
     }
   }
   

4. Replace <your_home_assistant_url> with the complete URL of your Home Assistant server, including http:// or https:// and the port, if required. For example, use http://homeassistant.local for a typical local connection. The callback port and the port in client_id must match. The client_id value is the base URL of the local OAuth callback used by OpenCode. Do not replace it with your Home Assistant URL.

5. Run the following command:

   opencode mcp auth homeassistant
   

6. Complete the authentication in your web browser and authorize OpenCode to access Home Assistant.

7. Run opencode mcp list to confirm that the server is connected. The Home Assistant tools appear with the prefix homeassistant_.

Example: Cursor

Cursor connects to Home Assistant through mcp-proxy. This local MCP server acts as a gateway to the Home Assistant MCP server. You also need a long-lived access token, which you can create in User profile > Security.

1. Download and install Cursor.

2. Install mcp-proxy following the instructions in the README. For example, uv tool install git+https://github.com/sparfenyuk/mcp-proxy.

3. Open the main Cursor Settings and select MCP.

4. Select Add new global MCP server and add the Home Assistant server configuration:

   {
     "mcpServers": {
       "Home Assistant": {
         "command": "mcp-proxy",
         "args": [
           "--transport=streamablehttp",
           "--stateless",
           "http://<your_local_home_assistant_ip_or_url>:8123/api/mcp"
         ],
         "env": {
           "API_ACCESS_TOKEN": "<your_access_token_here>"
         }
       }
     }
   }
   

5. Save your mcp.json file. You can also find this file in the $HOME/.cursor/mcp.json directory.

6. Restart Cursor and return to the MCP settings. You should see the Home Assistant server in the list. The indicator should be green.

7. In chat agent mode (Ctrl+I), ask it to control your home and the tool should be used.

Example: Antigravity CLI

1. Install the Antigravity CLI if you haven’t already. You can find installation instructions at https://antigravity.google.

2. Open the Antigravity CLI MCP configuration file, mcp_config.json. This is usually located at ~/.gemini/antigravity-cli/mcp_config.json. For more details, refer to the Antigravity CLI MCP server documentation.

3. Add the following to your mcpServers configuration:

   {
     "mcpServers": {
       "homeassistant": {
         "serverUrl": "https://<your_home_assistant_url>/api/mcp",
         "headers": {
           "Authorization": "Bearer ${HOMEASSISTANT_TOKEN}"
         }
       }
     }
   }
   

4. Replace <your_home_assistant_url> with the URL of your Home Assistant instance.

5. Set the HOMEASSISTANT_TOKEN environment variable to a Long-Lived Access Token from your Home Assistant instance.

6. Save the file. You can now use Home Assistant tools within the Antigravity CLI.

Example: Mistral Vibe

Mistral Vibe can connect to Home Assistant as a remote MCP server by using a long-lived access token. The Vibe CLI doesn’t support OAuth for MCP servers yet.

1. Install Mistral Vibe and run vibe once to complete the setup.

2. Create a long-lived access token in User profile > Security.

3. Set the HOMEASSISTANT_TOKEN environment variable to your access token in the shell where you start Vibe.

4. Open ~/.vibe/config.toml and add the following at the end of the file:

   [[mcp_servers]]
   name = "homeassistant"
   transport = "streamable-http"
   url = "<your_home_assistant_url>/api/mcp"
   api_key_env = "HOMEASSISTANT_TOKEN"
   api_key_header = "Authorization"
   api_key_format = "Bearer {token}"
   

5. Replace <your_home_assistant_url> with the complete URL of your Home Assistant instance, including the port if required. For example, use http://homeassistant.local:8123 for a typical local connection.

6. Start vibe and type /mcp to confirm the server is connected. The Home Assistant tools appear with the prefix homeassistant_.

Supported functionality

Tools

MCP Tools enable LLMs to perform actions through Home Assistant. The tools used by the configured LLM API are exposed.

Prompts

The MCP Prompts provided inform LLMs how to call the tools. The tools used by the configured LLM API are exposed.

Resources

When the configured LLM API includes the GetLiveContext tool, Home Assistant also exposes a read-only MCP Resource named homeassistant://assist/context-snapshot.

This resource returns a plain-text snapshot that matches the existing GetLiveContext tool output. It is intended for inspection, debugging, and explanation workflows where a static snapshot is useful. If the configured LLM API does not expose GetLiveContext, this resource is not available.

Known limitations

The Home Assistant Model Context Protocol integration currently only supports a subset of MCP features:

• Prompts: Supported
• Tools: Supported
• Resources: Supported (Assist only)
• Sampling: Not supported
• Notifications: Not supported

Troubleshooting

Repeated OAuth failures

Symptom: Unable to access Home Assistant after several failed login attempts

If authentication keeps failing during the OAuth setup flow, the most likely cause is that one or more OAuth details are incorrect, such as the client ID or the Home Assistant URL.

Resolution

1. Review the OAuth configuration in your client and verify the details:
   • Make sure the Client ID is the base URL of the LLM client application (for example, https://claude.ai for Claude or https://chatgpt.com for ChatGPT), and never your Home Assistant instance URL. IndieAuth validates that the redirect URI shares the same scheme and domain with the client ID; setting the client ID to your Home Assistant instance causes the authorization flow to fail.
   • Home Assistant does not use a client secret. If the field is required by the client application, enter any text; if it is optional, leave it blank.
   • Make sure the URL used to access Home Assistant matches the configured Internal URL or External URL in Settings > System > Network.
2. If you have explicitly enabled IP bans in Home Assistant and repeated failed sign-in attempts caused a ban, check the ip_bans.yaml file in your Home Assistant configuration directory. If your computer’s IP address or the client’s IP address is listed there, remove it, restart Home Assistant, and then try authenticating again.

Symptom: OAuth discovery fails or authorization server metadata is rejected

When connecting an external client (such as ChatGPT or Claude) through a tunnel, reverse proxy, or custom domain, the client fails to complete OAuth discovery or rejects the metadata with an error regarding the issuer or registration endpoint.

Description

This can occur for two reasons:

• Hostname or proxy mismatch: Home Assistant checks incoming requests against its configured internal and external URLs. If the hostname used by the remote LLM client does not match the configured URL, or if reverse-proxy headers (X-Forwarded-Host, X-Forwarded-Proto) are missing or mismatched, Home Assistant cannot resolve the issuer in /.well-known/oauth-authorization-server and returns relative paths. Conforming OAuth clients reject this metadata because RFC 8414 requires the issuer to match the URL used to discover it.
• Unsupported Dynamic Client Registration (RFC 7591): Home Assistant uses the draft-ietf-oauth-client-id-metadata-document standard (client_id_metadata_document_supported: true) rather than RFC 7591 Dynamic Client Registration. LLM clients that strictly require RFC 7591 Dynamic Client Registration cannot register automatically.

Resolution

1. Go to Settings > System > Network and make sure that the External URL (or Internal URL) matches the exact hostname and scheme used by the remote LLM client to reach Home Assistant.
2. If using a reverse proxy or tunnel (such as Cloudflare Tunnel), make sure Home Assistant is configured to trust forwarded headers from the proxy. See Reverse proxies in the HTTP integration documentation for details on configuring Trust X-Forwarded-For and Trusted proxies.
3. If the LLM client supports manual OAuth configuration (such as ChatGPT’s user-defined OAuth client), enter the authorization and token endpoints manually rather than relying on automatic discovery.
4. Using Home Assistant Cloud (https://<your-id>.ui.nabu.casa) avoids reverse-proxy and tunnel configuration pitfalls because it automatically handles canonical hostnames and SSL termination.

Removing the integration

This integration can be removed by following these steps:

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three dots menu. Then, select Delete.