Connect Home Assistant to Quok

Home Assistant can use Quok as an MCP tool provider. After setup, your conversation agent can read and change the family calendar, tasks, shopping, and lists from an Assist pipeline or voice satellite.

Before you start

You need:

• A family with Quok Plus
• A Quok organizer or adult to create OAuth credentials
• Home Assistant 2026.4.3 or later
• A Home Assistant conversation agent that can use external tools

Update Home Assistant before continuing if your version is older.

Create OAuth credentials in Quok

1. Open Connect your AI in Quok. You can also open Preferences → Connect an AI app in the web app.

2. Expand Connect your own app and name the connection, for example Home Assistant living room.

3. Under Where the app sends you back, select Home Assistant (my.home-assistant.io).

4. Choose Create credentials.

5. Keep this page open. Quok shows the server address, client ID, and client secret. The secret appears only once.

If your Home Assistant installation does not load the default my integration, select Custom callback URL instead. Enter your Home Assistant external URL followed by /auth/external/callback.

Add the credentials to Home Assistant

1. In Home Assistant, open Settings → Devices & services.

2. Open the three-dot menu in the top-right corner and choose Application credentials.

3. Choose Add application credential and select Model Context Protocol as the integration.

4. Enter a recognizable name, such as Quok.

5. Paste the client ID and client secret from Quok, then save.

Add Quok as an integration

1. Return to Settings → Devices & services and choose Add integration.

2. Search for and select Model Context Protocol.

3. Paste the Quok server address. It must end in /mcp, with no trailing slash or spaces.

4. Choose Use existing credentials and select the Quok credential you just saved.

5. Sign in to Quok in the browser window. Check the app name, your family, and the requested capabilities, then choose Allow access.

The integration usually appears as quok-mcp, using the identity reported by the Quok server.

Home Assistant’s public Model Context Protocol guide describes the integration and its current requirements.

Give your conversation agent access

Connecting the integration does not automatically make its tools available to every conversation agent.

1. Open Settings → Devices & services and select your conversation agent, such as ChatGPT.

2. Choose Configure.

3. Under Control Home Assistant, enable both Assist and quok-mcp.

4. Save the changes.

Without quok-mcp, Home Assistant can show the integration as connected while the agent never uses its tools.

Choose how shopping requests are handled

Home Assistant normally tries its local sentence rules before sending a request to the conversation agent. A phrase such as “Add cheese to the shopping list” can be intercepted by Home Assistant’s local shopping list instead of reaching Quok.

For natural Quok shopping requests:

1. Open Settings → Voice assistants.

2. Select the Assist pipeline used by your phone or voice satellite.

3. Turn off Prefer handling commands locally.

This sends every request in that pipeline to the conversation agent, including simple device commands. That can add time and model usage. To keep local handling on, include Quok in list requests, for example “Add cheese to the Quok shopping list.”

Guide the conversation agent

Add these instructions to the conversation agent:

Shopping lists and tasks live in Quok. Use the Quok tools for anything involving the
shopping list, groceries, tasks, or chores. There is no local Home Assistant list.
Do not ask which list unless there is genuine ambiguity between named Quok lists.

The last line stops the agent from asking which list you mean when the intended Quok list is already clear.

Check the connection

Test one write and one read through the same voice pipeline you plan to use:

• “Add cheese to the shopping list.”
• “What’s on the shopping list?”

Confirm that the new item appears in Quok and that the spoken answer matches the list.

Troubleshooting

Problem	What to check
Create credentials is unavailable in Quok	The family needs Quok Plus, and only an organizer or adult can create the credentials.
Home Assistant reports Failed to connect	Copy the server address from Quok again. Remove leading spaces and confirm it uses https://.
Home Assistant reports Unknown error	Remove trailing spaces and a trailing slash. The address must end exactly in /mcp.
OAuth reports an invalid client or callback	Recreate the Quok credentials with the Home Assistant callback preset, then replace the Application Credential in Home Assistant.
The integration connects but the agent never uses Quok	Enable quok-mcp in the conversation agent’s Control Home Assistant settings.
Shopping requests return an unexpected error	Turn off Prefer handling commands locally, or say Quok shopping list in the request.
The agent asks which list every time	Add the conversation-agent instructions above.

Disconnect Home Assistant

Remove the Model Context Protocol integration from Home Assistant. Then open Preferences → Connect an AI app → Connect your own app in Quok and revoke the Home Assistant app. Revoking it invalidates its OAuth tokens immediately.