alexandresanlim/home-assistant-switch-mcp-server

🚀 Home Assistant MCP Server

A Model Context Protocol (MCP) server providing Home Assistant integration for controlling smart home devices and getting entity states. Use this server as a tool provider in your MCP-compatible clients (like Claude, Cursor, and others) to interact with your Home Assistant instance. This is an unofficial repository.

One of the main motivations for this MCP server is security and control. Instead of exposing your entire Home Assistant REST API (which includes hundreds of endpoints and full system access), this server provides a curated set of specific tools that you can safely share with AI assistants.

🏠 Home Assistant Switch Tool

Example Usage:

https://github.com/user-attachments/assets/e7061d6a-faac-4d62-8a73-1449e7d156af

🤖 What is MCP?

Model Context Protocol (MCP) is a standard for tool providers to communicate with AI clients via standard input/output. This server lets you plug Home Assistant tools into any MCP-compatible client.

⚡ Quick Start: Use in Your MCP Client

You can configure this server as a tool provider in your MCP Client such as Claude, Cursor, VsCode and others:

"home-assistant-mcp-server-switch-local": {
  "command": "npx",
  "args": [
    "@sanlim/home-assistant-mcp-server"
  ],
  "env": {
    "HOME_ASSISTANT_URL": "your_host:8123",
    "HOME_ASSISTANT_TOKEN": "your_long_lived_access_token_here"
  }
}

🛠️ Using a Local Build

1. Clone this repository:

git clone https://github.com/alexandresanlim/home-assistant-switch-mcp-server.git

2. Install and build:

npm install
npm run build
npm run server

3. Configure your MCP client:

"home-assistant-mcp-server-debug": {
  "command": "node",
  "args": [
    "...replace_to_path_of_project/home-assistant-switch-mcp-server/build/main.js"
  ],
  "env": {
    "HOME_ASSISTANT_URL": "http:/localhost:8123",
    "HOME_ASSISTANT_TOKEN": "your_long_lived_access_token_here"
  }
}

The server will start and listen for MCP requests via standard input/output. 🎉

🔧 Configuration

Environment Variables

• HOME_ASSISTANT_URL: Your Home Assistant instance URL (default: http://localhost:8123)
• HOME_ASSISTANT_TOKEN: Your Home Assistant Long-Lived Access Token

Getting a Home Assistant Token

1. Log into your Home Assistant frontend
2. Go to your profile: http://YOUR_HA_URL/profile
3. Scroll down to "Long-Lived Access Tokens"
4. Create a new token and copy it

📚 Reference & Troubleshooting

• Full API reference: Home Assistant REST API docs
• If you have issues, make sure your build is up to date and your MCP client is configured to use stdio.
• For questions or contributions, feel free to open an issue or pull request!

Made with ❤️ by a Home Assistant enthusiast. Enjoy!