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.