Skip to content

# System Configuration

This document provides detailed information about configuring the Home Assistant MCP Server.

## Configuration File Structure

The MCP Server uses a hierarchical configuration structure:

    server:
      host: 0.0.0.0
      port: 8123
      log_level: INFO

    security:
      jwt_secret: YOUR_SECRET_KEY
      allowed_origins:
        - http://localhost:3000
        - https://your-domain.com

    devices:
      scan_interval: 30
      default_timeout: 10

## Server Settings

### Basic Server Configuration

- `host`: Server binding address (default: 0.0.0.0)
- `port`: Server port number (default: 8123)
- `log_level`: Logging level (INFO, DEBUG, WARNING, ERROR)

### Security Settings

- `jwt_secret`: Secret key for JWT token generation
- `allowed_origins`: CORS allowed origins list
- `ssl_cert`: Path to SSL certificate (optional)
- `ssl_key`: Path to SSL private key (optional)

### Device Management

- `scan_interval`: Device state scan interval in seconds
- `default_timeout`: Default device command timeout
- `retry_attempts`: Number of retry attempts for failed commands

## Environment Variables

Environment variables override configuration file settings:

    MCP_HOST=0.0.0.0
    MCP_PORT=8123
    MCP_LOG_LEVEL=INFO
    MCP_JWT_SECRET=your-secret-key

## Advanced Configuration

### Rate Limiting

    rate_limit:
      enabled: true
      requests_per_minute: 100
      burst: 20

### Caching

    cache:
      enabled: true
      ttl: 300  # seconds
      max_size: 1000  # entries

### Logging

    logging:
      file: /var/log/mcp-server.log
      max_size: 10MB
      backup_count: 5
      format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"

## Best Practices

1. Always use environment variables for sensitive information
2. Keep configuration files in a secure location
3. Regularly backup your configuration
4. Use SSL in production environments
5. Monitor log files for issues

## Validation

The server validates configuration on startup: - Required fields are checked - Value types are verified - Ranges are validated - Security settings are assessed

## Troubleshooting

Common configuration issues: 1. Permission denied accessing files 2. Invalid YAML syntax 3. Missing required fields 4. Type mismatches in values

See the Troubleshooting Guide for solutions.

February 6, 2025
February 6, 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