A Model Context Protocol Server for Home Assistant

The server uses the MCP protocol to share access to a local Home Assistant instance with an LLM application. It provides a comprehensive interface for controlling various Home Assistant entities through natural language.

Features

• Entity Control: Full support for controlling common Home Assistant entities:
  • 💡 Lights: Brightness, color temperature, RGB color
  • 🌡️ Climate: Temperature, HVAC modes, fan modes, humidity
  • 🚪 Covers: Position control, tilt control
  • 🔌 Switches: Basic on/off control
  • 🚨 Contacts: State monitoring
• Entity State Access: Query and monitor entity states
• Area and Floor Organization: Logical grouping of devices
• Robust Error Handling: Clear error messages and state validation

Prerequisites

• Node.js 16 or higher
• Yarn package manager
• A running Home Assistant instance
• A long-lived access token from Home Assistant

Installation

# Clone the repository
git clone https://github.com/yourusername/homeassistant-mcp.git
cd homeassistant-mcp

# Install dependencies
yarn install

# Build the server
yarn build

Configuration

1. Home Assistant Token

   • Get a long-lived access token from Home Assistant
   • Guide: How to get long-lived access token

2. Environment Variables Create a .env file with:

   TOKEN=your_home_assistant_token
   BASE_URL=your_home_assistant_url  # e.g., http://homeassistant.local:8123
   PORT=3000  # Optional, defaults to 3000
   

3. MCP Client Configuration Configure your MCP client (like Claude Desktop) with:

   {
       "mcpServers": {
           "homeassistant": {
               "command": "node",
               "args": [
                   "/path/to/dist/index.js"
               ],
               "env": {
                   "TOKEN": "your_home_assistant_token",
                   "BASE_URL": "your_home_assistant_url"
               }
           }
       }
   }
   

Supported Commands

Common Commands (All Entities)

• turn_on: Turn entity on
• turn_off: Turn entity off
• toggle: Toggle entity state

Light-Specific Commands

• Control brightness (0-255)

  {
    "command": "turn_on",
    "entity_id": "light.living_room",
    "brightness": 128
  }
  

• Set color temperature

  {
    "command": "turn_on",
    "entity_id": "light.living_room",
    "color_temp": 4000
  }
  

• Set RGB color values

  {
    "command": "turn_on",
    "entity_id": "light.living_room",
    "rgb_color": [255, 0, 0]
  }
  

Cover Commands

• open: Open cover

• close: Close cover

• stop: Stop cover movement

• set_position: Set cover position (0-100)

  {
    "command": "set_position",
    "entity_id": "cover.living_room",
    "position": 50
  }
  

• set_tilt_position: Set cover tilt (0-100)

  {
    "command": "set_tilt_position",
    "entity_id": "cover.living_room",
    "tilt_position": 45
  }
  

Climate Commands

• set_temperature: Set target temperature

  {
    "command": "set_temperature",
    "entity_id": "climate.living_room",
    "temperature": 22
  }
  

• set_hvac_mode: Set mode (off, heat, cool, heat_cool, auto, dry, fan_only)

  {
    "command": "set_hvac_mode",
    "entity_id": "climate.living_room",
    "hvac_mode": "heat"
  }
  

• set_fan_mode: Set fan mode (auto, low, medium, high)

  {
    "command": "set_fan_mode",
    "entity_id": "climate.living_room",
    "fan_mode": "auto"
  }
  

• set_humidity: Set target humidity (0-100)

  {
    "command": "set_humidity",
    "entity_id": "climate.living_room",
    "humidity": 45
  }
  

Development

# Run in development mode
yarn dev

# Build and start
yarn build:start

# Run tests
yarn test

Troubleshooting

Common Issues

1. Connection Errors

   • Verify your Home Assistant instance is running
   • Check the BASE_URL is correct and accessible
   • Ensure your token has the required permissions

2. Entity Control Issues

   • Verify the entity_id exists in Home Assistant
   • Check the entity domain matches the command
   • Ensure parameter values are within valid ranges

3. Permission Issues

   • Verify your token has write permissions for the entity
   • Check Home Assistant logs for authorization errors

Project Status

Completed

• Access to entities
• Access to Floors
• Access to Areas
• Control for entities
  • Lights
  • Thermostats
  • Covers
  • Contacts
  • Climates
  • Switches

In Progress

• Testing / writing custom prompts
• Testing using resources for high-level context
• Test varying tool organization

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• Model Context Protocol Documentation
• Home Assistant Documentation
• Home Assistant REST API