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)

```bash
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

```bash
# 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`:

```bash
# 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

```bash
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:

```json
{
  "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:**
```bash
# 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
```bash
chmod +x setup.sh
```

### TypeScript Errors
```bash
npm install
npm run build
```

### Home Assistant SSL Certificate Issues
If using HTTPS with self-signed certificate:
```bash
# 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! 🏠🤖