@sanlim/home-assistant-switch-mcp-server/README.md

A MCP server for Home Assistant switch services.

# 🚀 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:**

## 🤖 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:

```json
"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:**

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

2. **Install and build:**

```bash
npm install
npm run build
npm run server
```

3. **Configure your MCP client:**

```json
"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](https://developers.home-assistant.io/docs/api/rest/)
- 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!