Homeassistant MCP

🚀 Home Assistant Documentation

This documentation provides a comprehensive guide on configuring and using Home Assistant, including server configuration, input/output modes, integration with Claude Desktop, and more.

🚀 Quick Start

The following sections will guide you through the configuration and usage of Home Assistant.

📦 Installation Guide

MCP Server Configuration

Configuration File Example

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "HASS_TOKEN": "your_home_assistant_token_here",
        "HASS_HOST": "http://your_home_assistant_host:8123"
      }
    }
  }
}

Environment Variables

• HASS_TOKEN: The access token for Home Assistant.
• HASS_HOST: The URL of the Home Assistant service, formatted as http://IP:port.

Startup Script

Option 1: Run Directly with Node.js

node index.js

Option 2: Use npm Package

1. Install the MCP server:

npm install homeassistant-mcp

2. Start the server:

npx homeassistant-mcp

Use Home Assistant's Startup Script

Add the following content to the homeassistant.conf file:

[HomeAssistantMCP]
command=node
args=index.js
environment=HASS_TOKEN="your_token_here",HASS_HOST="http://IP:port"

Then restart the Home Assistant service.

💻 Usage Examples

Standard Input/Output Mode (_stdio)

Enable Standard Input/Output Mode

Add the following to the .env file:

USE_STDIO_TRANSPORT=true

Run the Script

Option 1: Run Directly with Node.js

node index.js --stdio

Option 2: Use npm Package

npx homeassistant-mcp --stdio

Option Parameters

• --debug: Enable debug mode.
• --rebuild: Force a project rebuild.
• --help: Display help information.

Standard Input/Output Message Format

Request Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "method": "tool-name",
  "params": {
    "param1": "value1",
    "param2": "value2"
  }
}

Response Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "result": {
    // Tool-specific result data
  }
}

Error Response Format

{
  "jsonrpc": "2.0",
  "id": "unique-request-id",
  "error": {
    "code": -32700,
    "message": "Error message",
    "data": {} // Optional error details
  }
}

Notification Format (Server to Client)

{
  "jsonrpc": "2.0",
  "method": "notification-type",
  "params": {
    // Notification data
  }
}

Supported Error Codes

Integration with Claude Desktop

Configuration Steps

Modify the Configuration File

Find or create the configuration file at the following path:

• macOS:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

• Linux:

nano ~/.config/Claude/claude_desktop_config.json

• Windows:

notepad %APPDATA%\Claude\claude_desktop_config.json

Add MCP Server Configuration

Add or modify the following content in the file:

{
  "mcpServers": {
    "homeassistant-mcp": {
      "command": "node",
      "args": ["index.js"],
      "env": {
        "HASS_TOKEN": "your_token_here",
        "HASS_HOST": "http://IP:port"
      }
    }
  }
}

Restart the Service

After saving the configuration file, restart the Claude Desktop service.

Example Usage

Start the MCP Server

npx homeassistant-mcp --stdio

Example Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "getWeather",
  "params": {
    "location": "Beijing"
  }
}

Example Response

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "temperature": 25,
    "condition": "Sunny"
  }
}

📚 Documentation

Error Handling

Common Errors and Solutions

• Error Code -32700: The requested JSON format is invalid. Please check if the request data conforms to the JSON standard.
• Error Code -32601: Method not found. Please confirm that the method name is correct and registered.
• Error Code -32000: Tool execution failed. Please check if the environment variables and dependencies are configured correctly.

Advanced Features

Logging

Enable debug mode to get detailed logs:

npx homeassistant-mcp --debug stdio

The log files are usually located in the logs folder of the project directory, depending on the project configuration.

Performance Tuning

• Memory Optimization: Use the --max-old-space-size parameter to limit the maximum memory usage of the V8 engine.

node --max-old-space-size=512 index.js --stdio

• Network Performance: Configure a proxy server or adjust the HTTP request timeout settings.

Security Precautions

• Access Control: Ensure that the MCP server only allows connections from trusted sources.
• Token Security: When storing and transmitting HASS_TOKEN, use a secure protocol (e.g., HTTPS) to prevent unauthorized access.
• Log Monitoring: Regularly review the log files to detect and handle potential security events.

Update Log

Version 1.0.0 (2023-10-05)

• Added support for standard input/output mode.
• Optimized the error handling mechanism.
• Improved the integration experience with Claude Desktop.

Version 0.9.0 (2023-08-10)

• Initial version released, providing basic functions.

Contact Information

For feedback or technical support, please visit the official documentation or contact the support team.