homeassistant-mcp/docs/troubleshooting.md

layout, title, nav_order

layout	title	nav_order
default	Troubleshooting	6

Troubleshooting Guide 🔧

This guide helps you diagnose and resolve common issues with MCP Server.

Quick Diagnostics

Health Check

First, verify the server's health:

curl http://localhost:3000/health

Expected response:

{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "homeAssistant": {
    "connected": true,
    "version": "2024.1.0"
  }
}

Common Issues

1. Connection Issues

Cannot Connect to MCP Server

Symptoms:

• Server not responding
• Connection refused errors
• Timeout errors

Solutions:

1. Check if the server is running:

   # For Docker installation
   docker compose ps
   
   # For manual installation
   ps aux | grep mcp
   

2. Verify port availability:

   # Check if port is in use
   netstat -tuln | grep 3000
   

3. Check logs:

   # Docker logs
   docker compose logs mcp
   
   # Manual installation logs
   bun run dev
   

Home Assistant Connection Failed

Symptoms:

• "Connection Error" in health check
• Cannot control devices
• State updates not working

Solutions:

1. Verify Home Assistant URL and token in .env:

   HA_URL=http://homeassistant:8123
   HA_TOKEN=your_long_lived_access_token
   

2. Test Home Assistant connection:

   curl -H "Authorization: Bearer YOUR_HA_TOKEN" \
        http://your-homeassistant:8123/api/
   

3. Check network connectivity:

   # For Docker setup
   docker compose exec mcp ping homeassistant
   

2. Authentication Issues

Invalid Token

Symptoms:

• 401 Unauthorized responses
• "Invalid token" errors

Solutions:

1. Generate a new token:

   curl -X POST http://localhost:3000/auth/token \
     -H "Content-Type: application/json" \
     -d '{"username": "your_username", "password": "your_password"}'
   

2. Verify token format:

   // Token should be in format:
   Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
   

Rate Limiting

Symptoms:

• 429 Too Many Requests
• "Rate limit exceeded" errors

Solutions:

1. Check current rate limit status:

   curl -I http://localhost:3000/api/state
   

2. Adjust rate limits in configuration:

   security:
     rateLimit: 100  # Increase if needed
     rateLimitWindow: 60000  # Window in milliseconds
   

3. Real-time Updates Issues

SSE Connection Drops

Symptoms:

• Frequent disconnections
• Missing state updates
• EventSource errors

Solutions:

1. Implement proper reconnection logic:

   class SSEClient {
       constructor() {
           this.connect();
       }
   
       connect() {
           this.eventSource = new EventSource('/subscribe_events');
           this.eventSource.onerror = this.handleError.bind(this);
       }
   
       handleError(error) {
           console.error('SSE Error:', error);
           this.eventSource.close();
           setTimeout(() => this.connect(), 1000);
       }
   }
   

2. Check network stability:

   # Monitor connection stability
   ping -c 100 localhost
   

4. Performance Issues

High Latency

Symptoms:

• Slow response times
• Command execution delays
• UI lag

Solutions:

1. Enable Redis caching:

   REDIS_ENABLED=true
   REDIS_URL=redis://localhost:6379
   

2. Monitor system resources:

   # Check CPU and memory usage
   docker stats
   
   # Or for manual installation
   top -p $(pgrep -f mcp)
   

3. Optimize database queries and caching:

   // Use batch operations
   const results = await Promise.all([
       cache.get('key1'),
       cache.get('key2')
   ]);
   

5. Device Control Issues

Commands Not Executing

Symptoms:

• Commands appear successful but no device response
• Inconsistent device states
• Error messages from Home Assistant

Solutions:

1. Verify device availability:

   curl http://localhost:3000/api/state/light.living_room
   

2. Check command syntax:

   # Test basic command
   curl -X POST http://localhost:3000/api/command \
     -H "Content-Type: application/json" \
     -d '{"command": "Turn on living room lights"}'
   

3. Review Home Assistant logs:

   docker compose exec homeassistant journalctl -f
   

Debugging Tools

Log Analysis

Enable debug logging:

LOG_LEVEL=debug
DEBUG=mcp:*

Network Debugging

Monitor network traffic:

# TCP dump for API traffic
tcpdump -i any port 3000 -w debug.pcap

Performance Profiling

Enable performance monitoring:

ENABLE_METRICS=true
METRICS_PORT=9090

Getting Help

If you're still experiencing issues:

1. Check the GitHub Issues
2. Search Discussions
3. Create a new issue with:
   • Detailed description
   • Logs
   • Configuration (sanitized)
   • Steps to reproduce

Maintenance

Regular Health Checks

Run periodic health checks:

# Create a cron job
*/5 * * * * curl -f http://localhost:3000/health || notify-admin

Log Rotation

Configure log rotation:

logging:
  maxSize: "100m"
  maxFiles: "7d"
  compress: true

Backup Configuration

Regularly backup your configuration:

# Backup script
tar -czf mcp-backup-$(date +%Y%m%d).tar.gz \
    .env \
    config/ \
    data/

FAQ

General Questions

Q: What is MCP Server?

A: MCP Server is a bridge between Home Assistant and Language Learning Models, enabling natural language control and automation of your smart home devices.

Q: What are the system requirements?

A: MCP Server requires:

• Node.js 16 or higher
• Home Assistant instance
• 1GB RAM minimum
• 1GB disk space

Q: How do I update MCP Server?

A: For Docker installation:

docker compose pull
docker compose up -d

For manual installation:

git pull
bun install
bun run build

Integration Questions

Q: Can I use MCP Server with any Home Assistant instance?

A: Yes, MCP Server works with any Home Assistant instance that has the REST API enabled and a valid long-lived access token.

Q: Does MCP Server support all Home Assistant integrations?

A: MCP Server supports all Home Assistant devices and services that are accessible via the REST API.

Security Questions

Q: Is my Home Assistant token secure?

A: Yes, your Home Assistant token is stored securely and only used for authenticated communication between MCP Server and your Home Assistant instance.

Q: Can I use MCP Server remotely?

A: Yes, but we recommend using a secure connection (HTTPS) and proper authentication when exposing MCP Server to the internet.

Troubleshooting Questions

Q: Why are my device states not updating?

A: Check:

1. Home Assistant connection
2. WebSocket connection status
3. Device availability in Home Assistant
4. Network connectivity

Q: Why are my commands not working?

A: Verify:

1. Command syntax
2. Device availability
3. User permissions
4. Home Assistant API access