homeassistant-mcp/docs/getting-started.md

Getting Started with Home Assistant MCP

This guide will help you get started with the Home Assistant MCP (Model Context Protocol).

Prerequisites

Before you begin, ensure you have:

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

Installation

1. Clone the repository:

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

2. Install dependencies:

   bun install
   

3. Copy the example environment file:

   cp .env.example .env
   

4. 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

1. Check the server is running:

   curl http://localhost:3000/api/health
   

2. List available devices:

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

3. 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:

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

Development

For development and contributing:

1. Fork the repository
2. Create a feature branch
3. Follow the Development Guide
4. Submit a pull request

Support

Need help? Check out:

• GitHub Issues
• Troubleshooting Guide
• FAQ