Home Assistant MCP

🚀 Family Assistant MCP Server

A Model Context Protocol (MCP) server project integrated with Home Assistant, offering smart home control capabilities.

🚀 Quick Start

📦 Installation

Install Home Assistant as per the instructions and obtain a long-lived access token.

• Home Assistant Getting Started Guide

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json%

✨ Features

💡 Prompts

The server provides prompts for the toolset in each domain.

🛠️ Tools

The server enables control over various Home Assistant domains. Currently supported:

• 💡 Lights: On/Off, brightness adjustment
• 🌡️ Climate: Temperature control, HVAC mode
• 🔒 Locks: Lock/Unlock functionality
• 🚨 Alarm Control Panel: Arm/Disarm the security system
• 💧 Humidifiers: Humidity control

Example tools include:

light-turn_on()
climate-turn_off()
alarm_control_panel-disarm()
lock-lock()
humidifier-turn_off()

📚 Documentation

⚙️ Configuration

Environment Variables

Create a .env file in the root directory with the following content:

HOMEASSISTANT_TOKEN=your_long_lived_access_token_here # Add after obtaining the long-lived access token in your Home Assistant instance
HOMEASSISTANT_BASE_URL=your_home_assistant_url_here # e.g., http://homeassistant.local:8123

🔧 Technical Details

🏗️ Build and Release

To prepare the distribution package:

1. Synchronize dependencies and update the lock file:

uv sync

2. Build the package distribution:

uv build

This will create source and wheel distributions in the dist/ directory.

3. Publish to PyPI:

uv publish

Note: You need to set PyPI credentials via environment variables or command-line flags:

• Token: --token or UV_PUBLISH_TOKEN
• Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

🐞 Debugging

Since the MCP server runs via standard input/output, debugging can be challenging. For the best debugging experience, we highly recommend using the MCP Inspector.

You can start the MCP Inspector by executing the following command via npm:

npx @modelcontextprotocol/inspector

🤝 Contribution Guidelines

📝 Code Standards

1. Keep the code concise and understandable.
2. Follow the project directory structure.
3. Include the issue number and description in the commit message.

🤝 How to Contribute

1. Fork the repository: git clone https://github.com/yourusername/home-assistant-mcp.git
2. Create a feature branch: git checkout -b feature/problemNumber
3. Commit your changes: git commit -m "feat: Problem description"
4. Push to the remote repository: git push origin feature/problemNumber
5. Create a pull request.

📦 Dependency Management

Use package.json to manage project dependencies. Run the following command to install dependencies:

npm install

📄 License

MIT License