yayoboy/Claude-Desktop-HA

Home Assistant MCP Server for Claude Desktop

MCP (Model Context Protocol) server to integrate Home Assistant with Claude Desktop. Monitor sensors, statistics, and history of your smart home directly from Claude.

Features

• 6+ Reading Tools - Entity states, entity lists, search, statistics, history
• Drag & drop installation - Drag the .mcpb file into Claude Desktop
• Advanced statistics - Trends, aggregations, historical analysis
• Multiple versions - Base (ready), Pro (36+ tools), Ultimate (190+ planned tools)

Requirements

• Claude Desktop installed
• Home Assistant running and accessible
• Home Assistant Long-Lived Access Token
• Node.js 18+ (only for manual installation)

Quick Installation

1. Get Home Assistant Token

1. Open Home Assistant
2. Go to Profile (icon at bottom left)
3. Scroll to Long-Lived Access Tokens
4. Click Create Token and name it "Claude MCP"
5. Copy the token (you won't see it again!)

2. Install the Bundle

1. Open Claude Desktop
2. Drag homeassistant-mcp-1.0.0.mcpb into the window
3. Enter your Home Assistant URL: http://homeassistant.local:8123
4. Paste the token
5. Done!

3. Verify

Ask Claude:

"Show me all my Home Assistant sensors"

Available Versions

Base v1.0 - Ready to use

File: homeassistant-mcp-1.0.0.mcpb

• 6 reading tools
• Read-only (safe)
• Drag & drop installation
• Production ready

Included tools:

Pro v2.0 - Full control

File: homeassistant-mcp-pro-2.0.0.mcpb

• 36+ tools (read + write)
• Device control
• Advanced analytics with ML
• Charts and CSV/PDF export
• Specialized beehive monitoring
• Requires compilation (npm run build)

Ultimate v3.0 - Complete suite

File: homeassistant-mcp-ultimate-3.0.0.mcpb

• 190+ planned tools
• Scene management
• Alert system with ML
• Energy optimizer
• 10 advanced categories
• Active development

Usage Examples

"What's the temperature in the bedroom?"
"Show hive weight statistics for the last week"
"List all temperature sensors"
"Search entities with 'humidity' in the name"
"Give me the last 24 hours history for sensor.power"

Time Syntax

• 24h ago - last 24 hours
• 7d ago - last week
• 30d ago - last month

Domain Filters

"List all switches"
"Show lights that are on"
"Find binary sensors"

Manual Installation

If drag & drop doesn't work:

# Extract the bundle
unzip homeassistant-mcp-1.0.0.mcpb -d homeassistant-mcp
cd homeassistant-mcp
npm install

Configure ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "homeassistant": {
      "command": "node",
      "args": ["/path/to/homeassistant-mcp/dist/index.js"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_token"
      }
    }
  }
}

Restart Claude Desktop.

Documentation

• QUICK_START.md - Quick start guide in 1 minute
• INSTALLATION.md - Detailed installation guide
• DOCUMENTATION.md - Complete documentation
• CHANGELOG.md - Version history
• HomeAssistant-MCP-Docs.zip - Full documentation archive

Troubleshooting

Claude doesn't see the server

1. Restart Claude Desktop completely
2. Check in Settings > Developer > MCP Servers
3. Verify URL and Token

Connection error

Verify that Home Assistant is reachable:

curl -H "Authorization: Bearer YOUR_TOKEN" \
     http://homeassistant.local:8123/api/states

Invalid token

1. Go to Home Assistant > Profile
2. Create a new token
3. Update the configuration
4. Restart Claude Desktop

Security

• Read-Only (Base v1.0): The server can only read data
• Dedicated token: Use a separate token for this MCP
• Revocable: You can revoke the token at any time
• Local: No data sent to external servers

Project Structure

Claude-Desktop-HA/
├── homeassistant-mcp-1.0.0.mcpb         # Base bundle (ready)
├── homeassistant-mcp-pro-2.0.0.mcpb     # Pro bundle
├── homeassistant-mcp-ultimate-3.0.0.mcpb # Ultimate bundle
├── HomeAssistant-MCP-Docs.zip           # Documentation
├── QUICK_START.md                       # Quick start
├── INSTALLATION.md                      # Installation guide
├── DOCUMENTATION.md                     # Complete docs
├── CHANGELOG.md                         # Versions
└── README.md                            # This file

Compatibility

• Home Assistant: 2024.x+
• Claude Desktop: Latest
• Node.js: 18+
• MCP SDK: 1.0.4+

Roadmap

• WebSocket real-time updates
• Embedded HTML dashboard
• Voice commands
• TensorFlow.js ML predictions
• MQTT/Zigbee support

Contributing

1. Test Base v1.0
2. Complete missing tools in Pro v2.0
3. Implement new categories in Ultimate v3.0
4. Improve documentation
5. Report bugs and suggest features

License

MIT License - See LICENSE for details.

Created for Home Assistant integration with Claude Desktop.