Home Assistant MCP Server

Instructions

Implementation Reference

• src/index.ts:164-181 (handler)

  The main handler function that implements the toggle_entity tool logic by validating inputs and calling the Home Assistant API to turn the entity on or off.

  private async toggleEntity(args: any) {
    if (!args.entity_id || !args.state) {
      throw new McpError(ErrorCode.InvalidParams, 'entity_id and state are required');
    }
  
    const response = await this.haClient.post('/api/services/homeassistant/turn_' + args.state, {
      entity_id: args.entity_id,
    });
  
    return {
      content: [
        {
          type: 'text',
          text: `Successfully turned ${args.state} ${args.entity_id}`,
        },
      ],
    };
  }

• src/index.ts:73-87 (schema)

  Input schema defining the parameters for the toggle_entity tool: entity_id (required string) and state (required string enum ['on','off']).

  inputSchema: {
    type: 'object',
    properties: {
      entity_id: {
        type: 'string',
        description: 'The entity ID to toggle (e.g., switch.bedroom)',
      },
      state: {
        type: 'string',
        description: 'The desired state (on/off)',
        enum: ['on', 'off'],
      },
    },
    required: ['entity_id', 'state'],
  },

• src/index.ts:70-88 (registration)

  Registration of the toggle_entity tool in the ListTools response, including name, description, and input schema.

  {
    name: 'toggle_entity',
    description: 'Toggle a Home Assistant entity on/off',
    inputSchema: {
      type: 'object',
      properties: {
        entity_id: {
          type: 'string',
          description: 'The entity ID to toggle (e.g., switch.bedroom)',
        },
        state: {
          type: 'string',
          description: 'The desired state (on/off)',
          enum: ['on', 'off'],
        },
      },
      required: ['entity_id', 'state'],
    },
  },

• src/index.ts:124-125 (helper)

  Switch case in the CallToolRequest handler that dispatches toggle_entity requests to the toggleEntity method.

  case 'toggle_entity':
    return await this.toggleEntity(request.params.arguments);