Initial commit
This commit is contained in:
Felix Zösch
249
QUICK_START.md
Normal file
249
QUICK_START.md
Normal file
@@ -0,0 +1,249 @@
|
||||
# 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! 🏠🤖
|
||||
Reference in New Issue
Block a user