Skip to content

# 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:
4. Detailed description
5. Logs
6. Configuration (sanitized)
7. 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

February 5, 2025
February 4, 2025
Was this page helpful?
Thanks for your feedback!
Thanks for your feedback! Please consider creating an issue to help us improve.

#### Cookie consent

We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.

- Google Analytics
- GitHub

Manage settings