SynapseHA

MCP server for Home Assistant providing 21 tools for LLM-driven control and maintenance.

✨ Key Features

• 🎯 Smart Resolution: Fuzzy search and typo-tolerant mapping for 3,200+ names
• 🎮 Full Control: Lights, climate, media, fans, and service calls
• 🔍 Deep Discovery: Explore topology, entity relationships, and device health
• 📊 Analytics: Live context, historical baselines, and anomaly detection
• ⚡ Performance: Persistent disk cache with 60s auto-refresh for <50ms responses

🏠 Home Assistant Add-on Installation

SynapseHA can be installed as a Home Assistant add-on for easy integration. The add-on runs an HTTP/SSE server that MCP clients can connect to.

Quick Install

1. Add this repository to Home Assistant

   

   Or manually:

   • Go to Settings → Add-ons → Add-on Store
   • Click the three dots menu (⋮) in the top right
   • Select Repositories
   • Add: https://github.com/hellosamblack/SynapseHA
   • Click Add → Close

2. Install the add-on

   • Find SynapseHA in the add-on store
   • Click Install

3. Start the add-on

   • Click Start
   • The add-on will automatically connect to your Home Assistant instance using the Supervisor API
   • The MCP server will be available at http://<homeassistant-ip>:3000

Connecting MCP Clients

Once the add-on is running, MCP clients can connect to:

• SSE endpoint: GET http://<homeassistant-ip>:3000/mcp
• Messages endpoint: POST http://<homeassistant-ip>:3000/messages?sessionId=<id>
• Health check: GET http://<homeassistant-ip>:3000/health

Add-on Configuration

The add-on supports the following configuration options:

Option	Default	Description
log_level	info	Logging level (debug, info, warn, error)
http_port	3000	HTTP port for MCP server
bearer_token	""	Optional bearer token for authentication
require_auth	false	Require authentication for connections
cache_refresh_interval	60	Cache refresh interval in seconds
entity_cache_enabled	true	Enable entity caching

⚙️ Configuration

Set the following environment variables:

export HA_URL="http://homeassistant.local:8123"
export HA_TOKEN="your_long_lived_access_token"
export CACHE_DIR="./cache"  # Optional, defaults to ./cache
export CACHE_TTL="60000"    # Optional, defaults to 60 seconds

Getting a Home Assistant Token

1. Open Home Assistant
2. Go to your profile (bottom left)
3. Scroll to "Long-Lived Access Tokens"
4. Click "Create Token"
5. Copy the token

Usage

Running the Server

npm start

🔌 Client Setup

Antigravity & VS Code (MCP Extension)

1. Install the connection:

   • Ensure you have the MCP Extension installed in VS Code.
   • Open your MCP Server Configuration (usually in .vscode/mcp.json or global settings).

2. Add the SynapseHA Server:

   If running via Home Assistant Add-on (Remote/Network): Use the URL where your Add-on is communicating.

   {
     "mcpServers": {
       "synapseha": {
         "url": "http://<homeassistant-ip>:3000/mcp"
       }
     }
   }

   Run Locally (Development only): If you are running this code locally (not on HA OS), point directly to the build:

   {
     "mcpServers": {
       "synapseha": {
         "command": "node",
         "args": ["f:/CastleBlackCode/SynapseHA/synapseha/dist/index.js"],
         "env": {
           "HA_URL": "http://homeassistant.local:8123",
           "HA_TOKEN": "your_long_lived_token"
         }
       }
     }
   }

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "synapseha": {
      "command": "node",
      "args": ["/absolute/path/to/SynapseHA/synapseha/dist/index.js"],
      "env": {
        "HA_URL": "http://homeassistant.local:8123",
        "HA_TOKEN": "your_token_here"
      }
    }
  }
}

🛠️ Available Tools (21 Total)

Entity Discovery (4 tools)

1. list_entities - List all entities or filter by domain (light, switch, climate, sensor)
2. search_entities - Fuzzy search entities by name with typo tolerance
3. get_entity_state - Get detailed state and attributes for specific entities
4. get_entity_relationships - Get relationships between entities, devices, and areas

Device Control (5 tools)

5. control_light - Control lights: on/off, brightness, color, temperature
6. control_climate - Control thermostats: temperature, mode, fan
7. control_media_player - Control media: play, pause, volume, source
8. control_fan - Control fans: speed, direction
9. control_switch - Control switches and smart plugs

Service Calls (1 tool)

10. call_service - Call any Home Assistant service with custom parameters

Topology & Discovery (4 tools)

11. get_areas - List all areas (rooms)
12. get_devices - List all devices with optional area filter
13. get_device_health - Check unavailable entities and low battery devices
14. list_services - List all available services by domain

Analytics (4 tools)

15. get_live_context - Get current state: active entities, recent changes
16. get_history - Get historical data for entities over time
17. calculate_baseline - Calculate statistics (avg, min, max, median)
18. detect_anomalies - Detect stuck sensors and anomalies

Automation (2 tools)

19. activate_scene - Activate a Home Assistant scene
20. trigger_automation - Trigger a Home Assistant automation

System Info (1 tool)

21. get_system_info - Get Home Assistant version, location, and entity counts

See API.md for detailed documentation of each tool.

🎯 Entity Resolution

SynapseHA features intelligent entity resolution that allows flexible device control:

// Use friendly names instead of entity IDs
{name: "living room lights"}  // → light.living_room_main

// Combine with area for disambiguation
{name: "temperature", area: "bedroom"}  // → sensor.bedroom_temperature

// Add floor for multi-level homes
{name: "lights", area: "bedroom", floor: "2"}  // → light.2f_bedroom_main

// Direct entity_id still works
{entity_id: "light.living_room"}

Name normalization: Handles variations like "living room" vs "livingroom", ignores special characters
Partial matching: Finds "temp" when searching for "temperature"
Domain preference: Prefers lights when multiple entity types match

💡 Example Usage

Ask Claude to:

• "Turn on the living room lights at 50% brightness"
• "What's the temperature in the bedroom?"
• "Show me all devices with low battery"
• "Find entities that haven't updated in the last hour"
• "What lights are currently on?"
• "Set the thermostat to 72 degrees"
• "Show me the history of the front door sensor for the last 24 hours"

🏗️ Architecture

SynapseHA/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── lib/
│   │   ├── ha-client.ts      # Home Assistant API wrapper
│   │   ├── cache.ts          # Persistent cache with auto-refresh
│   │   ├── fuzzy-search.ts   # Fuzzy matching for entities
│   │   └── name-resolver.ts  # Intelligent entity name resolution
│   ├── tools/
│   │   └── index.ts          # All 21 MCP tools
│   └── types/
│       └── index.ts          # TypeScript type definitions
├── dist/                     # Compiled JavaScript (ES modules)
└── cache/                    # Persistent disk cache

⚡ Performance

• Cache Hit: <50ms response time
• Cache Miss: ~200-500ms (API call + cache write)
• Auto-refresh: Every 60 seconds for entity states
• Fuzzy Search: ~5-10ms for 3,200+ entities

🔧 Development

# Watch mode for development
npm run watch

# Build for production
npm run build

# Run the server
npm start

See CONTRIBUTING.md for development guidelines.

📚 Documentation

• API.md - Complete API reference for all tools
• TROUBLESHOOTING.md - Common issues and solutions
• CHANGELOG.md - Version history and changes
• CONTRIBUTING.md - Development guide

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for details.

📝 License

ISC - See LICENSE file for details.

🙏 Acknowledgments

Built with:

• Model Context Protocol SDK - MCP implementation
• Home Assistant - Smart home platform
• Fuse.js - Fuzzy search library
• Axios - HTTP client

🐛 Issues & Support

• Check TROUBLESHOOTING.md first
• Search existing issues
• Create a new issue if needed

⭐ Star History

If you find SynapseHA useful, please consider giving it a star on GitHub!