ha-mcp-server/QUICK_START.md

Quick Start Guide

Get your Home Assistant MCP Server running in 5 minutes!

Prerequisites

• Node.js 18+ installed
• Running Home Assistant instance
• Home Assistant long-lived access token

Getting Your Access Token

1. Open Home Assistant in your browser
2. Click your profile picture (bottom left)
3. Scroll down to "Long-Lived Access Tokens"
4. Click "Create Token"
5. Give it a name (e.g., "MCP Server")
6. Copy the token immediately (you won't see it again!)

Installation

Option 1: Automated Setup (Recommended)

cd /Users/felix/Nextcloud/AI/projects/ha-mcp-server
./setup.sh

The script will:

• Check Node.js version
• Install dependencies
• Create and configure .env file
• Build the TypeScript code
• Test the connection to Home Assistant

Option 2: Manual Setup

# 1. Install dependencies
npm install

# 2. Create .env file
cp .env.example .env

# 3. Edit .env with your details
nano .env
# Set HA_BASE_URL and HA_ACCESS_TOKEN

# 4. Build the project
npm run build

# 5. Test it works
npm start

Configuration

Edit /Users/felix/Nextcloud/AI/projects/ha-mcp-server/.env:

# Your Home Assistant URL (with port)
HA_BASE_URL=http://homeassistant.local:8123

# Your long-lived access token
HA_ACCESS_TOKEN=eyJ0eXAiOiJKV1QiLCJhbGc...

Important:

• Include the port number (usually :8123)
• Use http:// or https:// prefix
• Use your local network address if using homeassistant.local doesn't work
• Example: http://192.168.1.100:8123

Testing the Server

npm start

You should see:

Successfully connected to Home Assistant
Home Assistant MCP Server running on stdio

Press Ctrl+C to stop.

Using with Claude Desktop

1. Find your Claude config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add this configuration:

{
  "mcpServers": {
    "home-assistant": {
      "command": "node",
      "args": ["/Users/felix/Nextcloud/AI/projects/ha-mcp-server/build/index.js"],
      "env": {
        "HA_BASE_URL": "http://homeassistant.local:8123",
        "HA_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

3. Replace:

   • Path to match your installation location
   • HA_BASE_URL with your Home Assistant URL
   • HA_ACCESS_TOKEN with your actual token

4. Restart Claude Desktop

5. Look for the 🔌 icon in Claude to see connected MCP servers

First Commands to Try

Once connected, try these with Claude:

Check Status

What entities do you have access to?

Control Lights

Turn on the living room lights

Check Temperature

What's the temperature in the bedroom?

Complex Query

How many lights are currently on?

Troubleshooting

"Cannot connect to Home Assistant"

Check:

• Is Home Assistant running?
• Can you access it in a browser?
• Is the URL in .env correct?
• Does the URL include the port number?

Try:

# Test with curl
curl -H "Authorization: Bearer YOUR_TOKEN" http://homeassistant.local:8123/api/

"Invalid access token"

Check:

• Token is copied correctly (no spaces)
• Token hasn't been revoked in Home Assistant
• Token is from the correct Home Assistant instance

Fix:

• Create a new token in Home Assistant
• Update .env with the new token
• Rebuild: npm run build

"Command not found" in Claude

Check:

• Path in claude_desktop_config.json is correct
• Build folder exists: /Users/felix/Nextcloud/AI/projects/ha-mcp-server/build/
• Run npm run build if build folder is missing

Claude doesn't show MCP connection

Check:

• claude_desktop_config.json syntax is valid JSON
• No trailing commas in JSON
• Restart Claude Desktop after config changes
• Check Claude Desktop logs

View logs:

• macOS: ~/Library/Logs/Claude/
• Windows: %APPDATA%\Claude\logs\

Common Issues

Port Already in Use

The server uses stdio (not a network port), so this shouldn't happen.

Permission Denied

chmod +x setup.sh

TypeScript Errors

npm install
npm run build

Home Assistant SSL Certificate Issues

If using HTTPS with self-signed certificate:

# Add to .env
NODE_TLS_REJECT_UNAUTHORIZED=0

⚠️ Only use this in development/private networks!

Verification Checklist

✅ Node.js 18+ installed ✅ Dependencies installed (npm install) ✅ .env file configured ✅ Project built (npm run build) ✅ Connection test passes (npm start) ✅ Claude config updated ✅ Claude Desktop restarted

Getting Help

1. Check the logs when running npm start
2. Read README.md for detailed documentation
3. Review EXAMPLES.md for usage patterns
4. Check Home Assistant logs for API errors

Next Steps

Once everything is working:

1. Explore capabilities: Read EXAMPLES.md
2. Understand architecture: Read ARCHITECTURE.md
3. Customize: Modify src/index.ts to add features
4. Secure: Use HTTPS and strong tokens in production

Security Reminders

• Never commit .env file
• Never share your access token
• Use HTTPS if exposing HA to internet
• Rotate tokens periodically
• Use separate tokens for different applications

Enjoy controlling your smart home with natural language! 🏠🤖