Skip to main content
Glama
homeassistant-ai

Home Assistant MCP Server

Official
by homeassistant-ai
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Create or Update Group

ha_config_set_group
Destructive

Create or update service-based Home Assistant entity groups via group.set to combine entities or edit members, for existing YAML or legacy group setups.

Instructions

Create or update a service-based Home Assistant entity group via the group.set service.

When NOT to use: for typical "combine these entities into one controllable group" requests, prefer ha_config_set_helper(helper_type="group", ...). Config-entry-backed groups are registered in the entity registry, so ha_set_entity can assign them to areas and they are deletable via ha_remove_helpers_integrations.

When to use: compatibility with existing groups already configured via group.set or YAML, or the rare case where entity-registry membership is explicitly unwanted. Groups created here are only removable via ha_config_remove_group — ha_remove_helpers_integrations will not find them.

For NEW groups: Provide object_id and entities (required). For EXISTING groups: Provide object_id and any fields to update. entities, add_entities, and remove_entities are mutually exclusive.

EXAMPLES:

  • Create: ha_config_set_group("bedroom_lights", entities=["light.lamp", "light.ceiling"], name="Bedroom Lights")

  • Add entities: ha_config_set_group("lights", add_entities=["light.extra"])

If a Claude Desktop user gets a 4-minute timeout with no result on this call, read the target back before repeating it, and tell them to wait a few seconds before clicking the manual-approve button, as clicking it too quickly is known to cause hangs in Claude Desktop. This workaround is specific to Claude Desktop.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
iconNoMaterial Design Icon (e.g., 'mdi:lightbulb-group')
nameNoFriendly display name for the group
waitNoWait for group to be queryable before returning. Set to False for bulk operations.
all_onNoIf True, all entities must be on for group to be on
entitiesNoList of entity IDs for the group. When updating, replaces all entities.
object_idYesGroup identifier without 'group.' prefix (e.g., 'living_room_lights')
add_entitiesNoAdd these entities to an existing group
remove_entitiesNoRemove these entities from an existing group

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault

No arguments

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed5 schema fields changedv8.6.0
    • changedInput schema / properties / add_entities / description
      Previous value: -"Add these entities to an existing group (mutually exclusive with entities)"New value: +"Add these entities to an existing group"
    • changedInput schema / properties / all_on / description
      Previous value: -"If True, all entities must be on for group to be on (default: False)"New value: +"If True, all entities must be on for group to be on"
    • changedInput schema / properties / entities / description
      Previous value: -"List of entity IDs for the group. Required when creating new group. When updating, replaces all entities (mutually exclusive with add_entities/remove_entities)."New value: +"List of entity IDs for the group. When updating, replaces all entities."
    • changedInput schema / properties / remove_entities / description
      Previous value: -"Remove these entities from an existing group (mutually exclusive with entities)"New value: +"Remove these entities from an existing group"
    • changedInput schema / properties / wait / description
      Previous value: -"Wait for group to be queryable before returning. Default: True. Set to False for bulk operations."New value: +"Wait for group to be queryable before returning. Set to False for bulk operations."
  2. First observedv7.14.2

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare destructiveHint=true, readOnlyHint=false, idempotentHint=false, and openWorldHint=false. The description adds lifecycle facts not in annotations: groups created here are only removable via ha_config_remove_group and invisible to ha_remove_helpers_integrations, and config-entry-backed alternatives behave differently. It also warns about a Claude Desktop timeout/hang workaround, which is valuable operational context beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded purpose followed by bolded when-not/when-to-use sections, parameter rules, and examples. The Claude Desktop timeout paragraph is longer than typical but is targeted operational guidance; overall there is little filler, though the description is more verbose than strictly needed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers creation and update modes, alternatives, lifecycle/removal path, mutual exclusivity, and examples. An output schema exists, so return values need not be explained. Complete for a destructive 8-parameter config tool with complex sibling alternatives.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3. The description adds conditional semantics—object_id plus entities required for new groups, any fields for updates, and mutual exclusivity among entities/add_entities/remove_entities—which goes beyond the schema's per-field descriptions. It does not clarify the roles of wait, all_on, or icon beyond what the schema already says.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('create or update') and resource ('service-based Home Assistant entity group via the group.set service'). It distinguishes the tool from the sibling ha_config_set_helper and explains the alternative. An agent can identify scope without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly names when NOT to use (prefer ha_config_set_helper) and when to use (compatibility with existing group.set/YAML groups, rare case where entity-registry membership is unwanted). It also states mutual exclusivity of entities/add_entities/remove_entities and the different required fields for new versus existing groups. Examples reinforce correct invocation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools