Home Assistant MCP Server

Instructions

Implementation Reference

• src/index.ts:148-162 (handler)

  The getEntityState method implements the core logic for the 'get_state' tool. It validates the entity_id parameter, queries the Home Assistant API for the entity's state, and returns the response as a formatted JSON text block.

  private async getEntityState(args: any) {
    if (!args.entity_id) {
      throw new McpError(ErrorCode.InvalidParams, 'entity_id is required');
    }
  
    const response = await this.haClient.get(`/api/states/${args.entity_id}`);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(response.data, null, 2),
        },
      ],
    };
  }

• src/index.ts:56-69 (schema)

  Defines the schema for the 'get_state' tool, including name, description, and input schema requiring 'entity_id'.

  {
    name: 'get_state',
    description: 'Get the current state of a Home Assistant entity',
    inputSchema: {
      type: 'object',
      properties: {
        entity_id: {
          type: 'string',
          description: 'The entity ID to get state for (e.g., light.living_room)',
        },
      },
      required: ['entity_id'],
    },
  },

• src/index.ts:122-123 (registration)

  Registers the 'get_state' tool in the CallToolRequestSchema handler by dispatching to the getEntityState method.

  case 'get_state':
    return await this.getEntityState(request.params.arguments);

• src/index.ts:54-117 (registration)

  Registers the 'get_state' tool in the ListToolsRequestSchema handler for tool discovery.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'get_state',
        description: 'Get the current state of a Home Assistant entity',
        inputSchema: {
          type: 'object',
          properties: {
            entity_id: {
              type: 'string',
              description: 'The entity ID to get state for (e.g., light.living_room)',
            },
          },
          required: ['entity_id'],
        },
      },
      {
        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'],
        },
      },
      {
        name: 'trigger_automation',
        description: 'Trigger a Home Assistant automation',
        inputSchema: {
          type: 'object',
          properties: {
            automation_id: {
              type: 'string',
              description: 'The automation ID to trigger (e.g., automation.morning_routine)',
            },
          },
          required: ['automation_id'],
        },
      },
      {
        name: 'list_entities',
        description: 'List all available entities in Home Assistant',
        inputSchema: {
          type: 'object',
          properties: {
            domain: {
              type: 'string',
              description: 'Optional domain filter (e.g., light, switch, automation)',
            },
          },
        },
      },
    ],
  }));