Homeassistant_mcp_server

silby1383/Homeassistant_mcp_server

3.2

If you are the rightful owner of Homeassistant_mcp_server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

HA Connect is a Model Context Protocol (MCP) server designed to integrate seamlessly with Home Assistant, offering a comprehensive suite of tools for managing and visualizing smart home data.

Tools
10
Resources
0
Prompts
0

HA Connect - Home Assistant MCP Server

A Model Context Protocol (MCP) server that connects to Home Assistant, providing tools for discovering entities, devices, states, history, and automations. Includes a lightweight Next.js frontend for configuration and visualization.

Features

MCP Server

  • Entity Discovery: Discover all entities and their current states
  • Device Discovery: Get information about all devices
  • State Management: Query and update entity states in real-time
  • Entity Control:
    • Turn entities on/off
    • Call any Home Assistant service
    • Set entity states directly
  • History: Retrieve historical data for entities
  • Automation Management:
    • Discover all automations
    • Create new automations from JSON configurations (via YAML files)
    • Update existing automations
  • Statistics: Get basic statistics about your Home Assistant instance

Frontend

  • Connection Setup: Easy configuration interface for connecting to Home Assistant
  • Entity Visualization: Browse and search all entities with filtering by domain
  • Device Browser: View all devices with manufacturer and model information
  • Automation Manager: View automation details and configurations
  • Statistics Dashboard: Visual charts and statistics about your Home Assistant setup

Prerequisites

  • Node.js 18+ and npm/yarn (for local development)
  • OR Docker and Docker Compose (for containerized deployment)
  • A Home Assistant instance running and accessible
  • A long-lived access token from Home Assistant

Installation

  1. Clone the repository:
git clone <repository-url>
cd haconnect
  1. Install dependencies:
npm install

Docker Deployment

For detailed Docker deployment instructions, see .

Development with Docker

For development with hot reload and live code changes:

Using Docker Compose (Recommended):

# Start development environment
docker-compose -f docker-compose.dev.yml up

# Or build and start
docker-compose -f docker-compose.dev.yml up --build

# Run in detached mode
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f

# Stop development environment
docker-compose -f docker-compose.dev.yml down

Using Docker directly:

# Build development image (stops at dependencies stage)
docker build -t haconnect:dev --target deps .

# Run with volume mounts for live reload
docker run -it --rm \
  --name haconnect-dev \
  -p 3000:3000 \
  -p 3101:3101 \
  -v $(pwd):/app \
  -v /app/node_modules \
  -v /app/.next \
  -v /app/dist \
  -v $(pwd)/config:/app/config:rw \
  -e NODE_ENV=development \
  haconnect:dev \
  sh -c "npm run dev & npm run mcp:dev & wait"

Development Notes:

  • Source code is mounted as a volume for live reload
  • Changes to code will automatically trigger rebuilds (Next.js and MCP server)
  • Use Ctrl+C to stop the container
  • Logs are shown in the terminal
  • node_modules, .next, and dist are excluded from volume mounts for better performance

Production with Docker

For production deployment with optimized builds:

Using Docker Compose (Recommended):

# Create config directory
mkdir -p config

# Build and start in detached mode
docker-compose up -d --build

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

# Restart the container
docker-compose restart

Using Docker directly:

# Build production image
docker build -t haconnect:latest .

# Run production container
docker run -d \
  --name haconnect \
  --restart unless-stopped \
  -p 3000:3000 \
  -p 3101:3101 \
  -v $(pwd)/config:/app/config:rw \
  haconnect:latest

# View logs
docker logs -f haconnect

# Stop the container
docker stop haconnect

# Remove the container
docker rm haconnect

Production Management:

# Update to latest version
docker-compose pull  # If using a registry
docker-compose up -d --build

# Check container status
docker-compose ps
# Or
docker ps | grep haconnect

# View resource usage
docker stats haconnect

# Access container shell
docker exec -it haconnect sh

Access the application:

The container runs both the Next.js frontend and MCP server. Configuration is persisted in the config directory.

Configuration

Getting a Home Assistant Access Token

  1. Open your Home Assistant instance
  2. Go to your profile (click on your user icon in the bottom left)
  3. Scroll down to "Long-Lived Access Tokens"
  4. Click "Create Token"
  5. Give it a name (e.g., "MCP Server")
  6. Copy the token (you won't be able to see it again)

Setting Up the Connection

  1. Start the Next.js development server:
npm run dev
  1. Open http://localhost:3000 in your browser
  2. You'll be redirected to the setup page
  3. Enter your Home Assistant URL (e.g., http://homeassistant.local:8123 or http://192.168.1.100:8123)
  4. Enter your long-lived access token
  5. Click "Test Connection" to verify
  6. Click "Save & Continue" to proceed to the dashboard

Usage

Running the MCP Server

The MCP server can be run independently for use with MCP-compatible clients:

# Development mode (with watch)
npm run mcp:dev

# Build
npm run mcp:build

# Production
npm run mcp:start

MCP Server Configuration

The MCP server reads configuration from config/ha-config.json. This file is automatically created when you save the configuration through the frontend.

Integrating with LLM Clients

The MCP server can be integrated with LLM clients:

  • Claude Desktop: Full MCP support - See
  • Cursor IDE: Full MCP support - See
  • ChatGPT: Requires HTTP endpoints (not currently supported) - See

Quick Setup for Claude Desktop:

./scripts/setup-mcp-claude.sh

Quick Setup for Cursor:

./scripts/setup-mcp-cursor.sh

MCP Tools

The server provides the following tools:

  • ha_test_connection - Test connection to Home Assistant
  • ha_get_entities - Get all entities
  • ha_get_entity - Get a specific entity by ID
  • ha_get_devices - Get all devices
  • ha_get_automations - Get all automations
  • ha_get_automation - Get a specific automation by ID
  • ha_get_history - Get history for entities
  • ha_create_automation - Create a new automation
  • ha_update_automation - Update an existing automation
  • ha_get_statistics - Get statistics for entities

Frontend Usage

  1. Dashboard: View all discovered entities, devices, automations, and statistics
  2. Entity Browser: Search and filter entities by domain
  3. Device Browser: View device information including manufacturer and model
  4. Automation Manager: View automation configurations and details
  5. Statistics: See charts and metrics about your Home Assistant setup

Development

Project Structure

haconnect/
├── src/
│   ├── app/                 # Next.js app directory
│   │   ├── api/            # API routes
│   │   ├── dashboard/      # Dashboard page
│   │   └── setup/          # Setup page
│   ├── components/         # React components
│   ├── lib/                # Utilities and hooks
│   ├── mcp-server/         # MCP server implementation
│   └── shared/             # Shared types and client
├── config/                 # Configuration files (gitignored)
└── dist/                   # Build output (gitignored)

Scripts

  • npm run dev - Start Next.js development server
  • npm run build - Build Next.js application
  • npm run start - Start Next.js production server
  • npm run mcp:dev - Start MCP server in development mode
  • npm run mcp:build - Build MCP server
  • npm run mcp:start - Start MCP server in production
  • npm run lint - Run ESLint
  • npm run type-check - Run TypeScript type checking

API Endpoints

The frontend provides the following API endpoints:

  • POST /api/test-connection - Test Home Assistant connection
  • GET /api/config - Get saved configuration
  • POST /api/config - Save configuration
  • GET /api/entities - Get all entities
  • GET /api/devices - Get all devices
  • GET /api/automations - Get all automations
  • POST /api/automations - Create new automation
  • PUT /api/automations/[id] - Update automation
  • GET /api/statistics - Get statistics

Security Notes

  • Access tokens are stored in config/ha-config.json (not committed to git)
  • The frontend stores configuration in browser localStorage
  • Always use HTTPS in production
  • Keep your access tokens secure and rotate them regularly

Troubleshooting

Connection Issues

  • Verify your Home Assistant URL is correct and accessible
  • Check that your access token is valid and hasn't been revoked
  • Ensure Home Assistant is running and the API is enabled
  • Check browser console and network tab for errors

MCP Server Issues

  • Verify the configuration file exists at config/ha-config.json
  • Check that the Home Assistant URL and token are correct
  • Ensure the MCP server has network access to your Home Assistant instance

License

MIT