Getting Started with Home Assistant MCP

This guide will help you get started with the Home Assistant MCP (Master Control Program).

Prerequisites

Before you begin, ensure you have:

Node.js (v16 or higher)
A running Home Assistant instance
A Home Assistant Long-Lived Access Token

Installation

Clone the repository:

git clone https://github.com/yourusername/homeassistant-mcp.git
cd homeassistant-mcp

Install dependencies:
```
bun install
```
Copy the example environment file:
```
cp .env.example .env
```

Edit the .env file with your configuration:

# Server Configuration
PORT=3000
BUN_ENV=development

# Home Assistant Configuration
HASS_HOST=http://your-hass-instance:8123
HASS_TOKEN=your-long-lived-access-token

# Security Configuration
JWT_SECRET=your-secret-key

Configuration

Environment Variables

PORT: The port number for the MCP server (default: 3000)
BUN_ENV: The environment mode (development, production, test)
HASS_HOST: Your Home Assistant instance URL
HASS_TOKEN: Your Home Assistant Long-Lived Access Token
JWT_SECRET: Secret key for JWT token generation

Development Mode

For development, you can use:

bun run dev

This will start the server in development mode with hot reloading.

Production Mode

For production, build and start the server:

bun run build
bun start

First Steps

Check the server is running:
```
curl http://localhost:3000/api/health
```

List available devices:

curl -H "Authorization: Bearer your-token" http://localhost:3000/api/tools/devices

Subscribe to events:

curl -H "Authorization: Bearer your-token" http://localhost:3000/api/sse/subscribe?events=state_changed

Next Steps

Read the API Documentation for available endpoints
Learn about Server-Sent Events for real-time updates
Explore available Tools for device control
Check the Configuration Guide for advanced settings

Troubleshooting

If you encounter issues:

Verify your Home Assistant instance is accessible
Check your environment variables are correctly set
Look for errors in the server logs
Consult the Troubleshooting Guide

Development

For development and contributing:

Fork the repository
Create a feature branch
Follow the Development Guide
Submit a pull request

Support

Need help? Check out:

2.7 KiB Raw Blame History