Skip to content

# Usage Guide

This guide explains how to use the Home Assistant MCP Server for basic device management and integration.

## Basic Setup

1. Starting the Server:
2. Development mode: `bun run dev`

3. Production mode: `bun run start`

4. Accessing the Server:

5. Default URL: `http://localhost:3000`
6. Ensure Home Assistant credentials are configured in `.env`

## Device Control

### REST API Interactions

Basic device control can be performed via the REST API:

    // Turn on a light
    fetch('http://localhost:3000/api/control', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${token}`
      },
      body: JSON.stringify({
        entity_id: 'light.living_room',
        command: 'turn_on',
        parameters: { brightness: 50 }
      })
    });

### Supported Commands

- `turn_on`
- `turn_off`
- `toggle`
- `set_brightness`

### Supported Entities

- Lights
- Switches
- Climate controls
- Media players

## Real-Time Updates

### WebSocket Connection

Subscribe to real-time device state changes:

    const ws = new WebSocket('ws://localhost:3000/events');
    ws.onmessage = (event) => {
      const deviceUpdate = JSON.parse(event.data);
      console.log('Device state changed:', deviceUpdate);
    };

## Authentication

All API requests require a valid JWT token in the Authorization header.

## Limitations

- Basic device control only
- Limited error handling
- Minimal third-party integrations

## Troubleshooting

1. Verify Home Assistant connection
2. Check JWT token validity
3. Ensure correct entity IDs
4. Review server logs for detailed errors

## Configuration

Configure the server using environment variables in `.env`:

    HA_URL=http://homeassistant:8123
    HA_TOKEN=your_home_assistant_token
    JWT_SECRET=your_jwt_secret

## Next Steps

- Explore the API Documentation
- Check Troubleshooting Guide
- Review Contributing Guidelines

February 5, 2025
February 4, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings