Early Access

The Google Home Model Context Protocol (MCP) server allows AI-powered
development tools and virtual assistants to interact directly with smart home
environments. By exposing standard MCP tools and RPC interfaces, the server
enables Large Language Models (LLMs) to inspect home structures, monitor device
states, execute control actions, and analyze historical events.

<br />

> ### **Warning!**
>
> Connecting a real-life home to an AI agent allows
> that agent to control devices on your behalf. Home MCP
> enforces rate limits and safety protections, such as prohibiting sensitive
> actions like unlocking doors. However, depending on your agent, connecting it
> to Home MCP can result in unexpected or even undesired behavior. Carefully
> review developer [policies](https://developers.home.google.com/policies.md.txt) and [terms
> of service](https://developers.home.google.com/terms).
>
> If you choose to connect a Google Home used by other household members with
> Home MCP, you should inform them that your agent can control devices and
> access home data. Alternatively, you can
> [create an
> additional home](https://support.google.com/googlehome/answer/17074648) and set up devices for development and testing.
>
> Your agent's access to Home MCP can be
> [revoked](https://support.google.com/googlehome/answer/14658393) at
> any time from the Google Home app (GHA) or your My Accounts page.

<br />

## Overview

An MCP server acts as a proxy between smart home infrastructure and AI
applications. The Home MCP server exposes executable tools that allow AI
clients to query real-time home telemetry and issue commands.

### Core capabilities

The Home MCP server provides several core capability areas:

- **Structure discovery:** Retrieve accessible homes and structures using [`list_homes`](https://developers.home.google.com/reference/home/mcp/tools_list/list_homes).
- **Resource discovery:** List devices, area layouts, traits, attributes, and command schemas using [`list_home_resources`](https://developers.home.google.com/reference/home/mcp/tools_list/list_home_resources.md.txt).
- **State monitoring:** Check real-time device connectivity status and trait states using [`list_home_states`](https://developers.home.google.com/reference/home/mcp/tools_list/list_home_states.md.txt).
- **Device control:** Execute parameterized action commands on target devices using [`run_home_actions`](https://developers.home.google.com/reference/home/mcp/tools_list/run_home_actions.md.txt).
- **Historical analysis:** Query past state changes and event logs over specific time ranges using [`list_home_history`](https://developers.home.google.com/reference/home/mcp/tools_list/list_home_history.md.txt).
- **Automations:** List automations using [`list_automations`](https://developers.home.google.com/reference/home/mcp/tools_list/list_automations.md.txt) and save an automation using [`save_automation`](https://developers.home.google.com/reference/home/mcp/tools_list/save_automation.md.txt).

## Supported traits

For a list of traits supported by Home MCP, see
[Supported traits](https://developers.home.google.com/mcp/home/supported-traits.md.txt).

## Prerequisites

Before setting up the Home MCP server, ensure you have the following:

- An active smart home setup in Google Home with connected devices.
- An active Google Home Premium Advanced subscription.
- Access to a Google Cloud project.
- An MCP-compatible AI client or application, such as Google Antigravity, Claude Cowork, or OpenClaw.

## Configure the MCP server

Setting up the MCP server requires creating a Google Cloud project,
obtaining access approval, enabling the Home API, and generating OAuth
credentials.

### Create a Google Cloud project

If you don't have a Google Cloud already, you must create one:

1. Open the [Google Cloud
   console](https://console.cloud.google.com/).
2. Create a new Google Cloud project.

For more information, see [Create
projects](https://docs.cloud.google.com/resource-manager/docs/creating-managing-projects)
article in the Google Cloud documentation.

### Enable the Home API

1. In the Google Cloud console navigation menu, select **APIs \&
   Services** \> **Enabled APIs \& Services**.
2. Search for **Home API** and click **Enable**.

### Configure OAuth consent and credentials

1. Configure the OAuth consent screen:
   1. Open **APIs \& Services** \> **OAuth consent screen**.
   2. Select **External** audience, click **Get started**, and fill in the required app information and contact email.
2. Create an OAuth client ID:
   1. Open **APIs \& Services** \> **Credentials**.
   2. Click **+ Create credentials** and select **OAuth client ID**.
   3. Set **Application type** to **Web application**.
   4. Add the authorized redirect URIs corresponding to your target AI clients:
      - Google Antigravity: `https://antigravity.google/oauth-callback`
      - Claude Cowork: `https://claude.ai/api/mcp/auth_callback`
      - OpenClaw: a pinned loopback URI that matches `mcp-remote` such as `http://127.0.0.1:8989/oauth/callback`
   5. Click **Create** and copy your **Client ID** and **Client Secret** to a secure location.
3. Publish your application:
   1. Open **Google Auth Platform** \> **Audience**.
   2. Under **Publishing status** , click **Publish app**.

## Configure your AI client

You can configure several AI development environments to connect to the Home
MCP server using OAuth authentication. Enter your OAuth Client ID and Client
Secret here, then follow your preferred setup instructions.

    Enter your Client ID: YOUR_CLIENT_ID
    Enter your Client Secret: YOUR_CLIENT_SECRET

### Automated setup using a prompt

If your AI assistant supports managing MCP tool configurations directly from
chat, you can instruct your assistant to configure the server by pasting the
following prompt:

    Please configure the Home MCP server for me with these settings:
    - Name: home_mcp
    - Server URL: https://home.googleapis.com/mcp
    - Transport: streamable-http
    - OAuth Scope: https://www.googleapis.com/auth/home.platform.v2
    - Client ID: YOUR_CLIENT_ID
    - Client Secret: YOUR_CLIENT_SECRET

### Manual setup

Select your preferred AI tool for manual setup instructions.

### Antigravity

Google Antigravity provides built-in integration for MCP servers across its
CLI, IDE, and desktop environments.

1. Open the application configuration menu: **Settings** \> **Advanced settings** \> **Customizations** \> **Open MCP Config**.
2. Add the `home_mcp` entry under the `mcpServers` configuration object:

   ```json
   {
     "mcpServers": {
       "home_mcp": {
         "serverUrl": "https://home.googleapis.com/mcp",
         "oauth": {
           "clientId": "YOUR_CLIENT_ID",
           "clientSecret": "YOUR_CLIENT_SECRET"
         }
       }
     }
   }
   ```
3. Complete authentication: Navigate to **Settings** \> **Advanced settings** \>
   **Customizations** \> **home_mcp** \> **Authentication**.

4. Complete the Google Home permissions flow in your web browser, select your
   home structure, and copy the authorization code back into Antigravity.

For more information, see the [Google Antigravity
documentation](https://antigravity.google/docs/mcp).

### Claude

Configure Claude Cowork to connect to your custom home MCP server:

1. Open [Claude
   Connectors](https://claude.ai/customize/connectors).
2. Click **+** and select **Add custom connector**.
3. Enter the server URL: `https://home.googleapis.com/mcp`.
4. Click **Advanced settings** and enter your **Client ID** and **Client Secret**.
5. Click **Add** and complete the OAuth authorization flow in your browser.
6. In a Cowork chat, click **+** in the lower-left corner, select **Connectors** , and toggle **home_mcp** on.

For more information, see the [Claude Platform
documentation](https://platform.claude.com/docs/en/home).

### OpenClaw

OpenClaw doesn't support a native static OAuth client. For the time being, you
can bridge `stdio` to Streamable HTTP through `mcp-remote`.

1. Create a local JSON file named `~/.openclaw/home-mcp-client.json`
   containing your Google Cloud OAuth credentials so that they aren't passed
   directly on the command line.

   ```json
   {
     "client_id": "YOUR_CLIENT_ID",
     "client_secret": "YOUR_CLIENT_SECRET"
   }
   ```
2. Restrict the permissions on this file so only your local account can read
   it:

       chmod 600 ~/.openclaw/home-mcp-client.json

3. Register the server in OpenClaw using `mcp-remote`. Replace
   `/absolute/path/to` with the full path to your
   credentials directory (`mcp-remote` doesn't expand `~`). The
   `--transport http-only` flag forces Streamable HTTP, `--host 127.0.0.1`
   matches the registered redirect URI, and `--authorize-param` requests a
   refresh token:

       openclaw mcp set home_mcp '{
         "command": "npx",
         "args": [
           "-y",
           "mcp-remote",
           "https://home.googleapis.com/mcp",
           "8989",
           "--host", "127.0.0.1",
           "--transport", "http-only",
           "--authorize-param", "access_type=offline",
           "--authorize-param", "prompt=consent",
           "--static-oauth-client-info",
             "@/absolute/path/to/home-mcp-client.json"
         ]
       }'

4. Restart the OpenClaw gateway:

       openclaw gateway restart

5. Run `openclaw mcp probe home_mcp` to complete browser sign-in and verify
   tool discovery.

For more information, see the [OpenClaw
documentation](https://docs.openclaw.ai).

## Familiar face consent

To access familiar faces data in the Home MCP, users must explicitly consent to
this feature separately.

### Prerequisites

- The user granting consent must be a manager of the Google Home structure.
- The user's structure must have at least one compatible Google Nest camera or doorbell and an active Google Home Premium subscription with **Familiar face detection** enabled for *each camera or doorbell*.
- Your application must have an OAuth 2.0 Client ID created in Google Cloud. See [Configure your AI
  client](https://developers.home.google.com/mcp/home#configure_your_ai_client) to create an OAuth 2.0 Client if you haven't already done so.

### Consent links

To grant your application access, you must visit a consent link personalized
with your OAuth 2.0 Client ID and Home Structure ID. There
are two ways to get your consent link.

Once you have your link, visit it and provide consent.

### Agent creates the link

If your agent is already connected to the Home MCP, it can
automatically locate your Home Structure ID and
generate a ready-to-click link.

Update the following parameters directly on this page, then copy-paste
the customized prompt into your agent's chat.

- <var class="edit" scope="CLIENT_ID" translate="no">CLIENT_ID</var> --- Your OAuth 2.0 Client ID from Google Cloud. For example, \`123456789-xyz.apps.googleusercontent.com\`.
- <var class="edit" scope="STRUCTURE_NAME" translate="no">STRUCTURE_NAME</var> --- The name of the target Home structure.

```
Please query my Home MCP to find the
Structure ID for my home named STRUCTURE_NAME. Once found, display
the structure name and ID, generate my clickable Familiar Faces Consent Link by
replacing <STRUCTURE_ID> in this URL with the structure ID you found:
https://home.google.com/connections/feature_consent?client_id=CLIENT_ID&structure_id=<STRUCTURE_ID>&features=1&continue=https%3A%2F%2Fhome.google.com

```

### You create the link

If your agent is already connected to the Home MCP, it can
automatically locate your Home Structure ID and
generate a ready-to-click link.

Update the following parameters directly on this page, then open the
customized link in a web browser.

- <var class="edit" scope="CLIENT_ID" translate="no">CLIENT_ID</var> --- Your OAuth 2.0 Client ID from Google Cloud. For example, \`123456789-xyz.apps.googleusercontent.com\`.
- <var class="edit" scope="STRUCTURE_ID" translate="no">STRUCTURE_ID</var> --- The UUID of the target Home structure. The easiest way to get this is to ask your agent using the Home MCP, "Tell me the structure ID (UUID) for \[Structure Name\]."

```
https://home.google.com/connections/feature_consent?client_id=CLIENT_ID&structure_id=STRUCTURE_ID&features=1&continue=https%3A%2F%2Fhome.google.com
```

## Verify connection and functionality

Once your client is configured and authenticated, verify the server
connection:

1. Launch your AI assistant or workspace session.
2. Check active MCP server connections (in Antigravity, run `/mcp` or inspect tool lists).
3. Confirm that `home_mcp` is listed with active tools.
4. Issue sample prompts to your assistant to test different capabilities:

   - **Entity discovery:** `How many lights do I have in my house?`
   - **Real-time state monitoring:** `Is my home secured?`
   - **Device control:** `Turn off all the outside lights.`
   - **Historical event analysis:** `What happened while I was out?`
5. Grant tool execution permissions when prompted by your client. The AI
   assistant can retrieve real-time state data and all responses will be
   grounded in your home telemetry.

## Publish a personal use MCP app

If you have your own website URL, privacy policy, and terms of service links,
you can proceed with completing the Branding section and then publish the app to
Production.

Otherwise, as a workaround, you can run the app in Test. To do this, complete
the Branding section using your own Google Account or other members' Google
Accounts as test users.

> [!IMPORTANT]
> **Important:** When running in Test, you must re-authenticate every 7 days to re-establish the OAuth permissions.

## Support

For Home MCP development support, head to the [Smart Home for Developers Help
Community](https://support.google.com/googlehome/community?product_label=gh-developer)
There you can post a question to get help, or look through previously posted
questions to see if your question has already been answered.

To file a MCP bug or feature request, head to our [public issue
tracker](https://issuetracker.google.com/issues/new?component=655104&template=2399599).

### Known issues

- Entitlement Enforcement --- Home MCP access should be restricted to users with a Google Home Premium Advanced subscription. A bug allows Nest Aware Plus subscribers to have Home MCP access. We're working to address this issue and a fix will be released soon.
- Trait Testing --- To provide the broadest set of functionality for your agents we've included some traits that are marked experimental. You may encounter scenarios where these experimental traits don't work as expected. If so, please use the [public issue
  tracker](https://issuetracker.google.com/issues/new?component=655104&template=2399599) to report.
- Latency --- At times you may notice longer than expected latency with Home MCP. We are actively working on optimizations. Expect to see latency improvements in future releases.