Files

jango-blockchained b55a75df54 Add Jest configuration files and enhance README with features and usage instructions

- Introduced `jest.config.cjs` and `jest.config.js` for Jest testing configuration.
- Expanded README.md to include detailed features, installation, configuration, and troubleshooting sections.
- Updated TypeScript configuration to target ES2022 and allow JavaScript files.
- Enhanced command handling in `src/index.ts` to support additional parameters for lights, covers, and climate entities.
- Added unit tests for command execution and Home Assistant connection validation.
- Updated schemas to include new entity types and parameters for better validation.

2024-12-16 13:30:20 +01:00

5.3 KiB

Raw Blame History

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

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

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

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

Connection Errors
- Verify your Home Assistant instance is running
- Check the BASE_URL is correct and accessible
- Ensure your token has the required permissions
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
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.

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

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

5.3 KiB Raw Blame History