Ha Mcp File Server

БесплатноНе проверен

Ha Mcp File Server — Model Context Protocol server

Описание

Ha Mcp File Server — Model Context Protocol server

README

A simple Model Context Protocol (MCP) server addon for Home Assistant that allows remote file management through MCP clients.

Features

File Operations: List, read, write, create, and delete files and directories
Search: Search for text patterns within files
HA CLI Commands: Execute Home Assistant CLI commands safely (optional)
HA Service Calls: Call allowlisted Home Assistant services, including reloads and setpoints (optional)
Entity Management: List and filter Home Assistant entities, devices, and services
Historical Analysis: Retrieve and analyze historical entity state changes for HVAC optimization and debugging
Log Diagnostics: Query Home Assistant logs by time, level, logger, and message text
MCP Add-on Management: Inspect MCP runtime flags, add-on config, logs, stats, and restart the add-on
Automation Debugging: Validate YAML, run config checks, and read automation traces
Security: API key authentication and path validation
Configurable: Set allowed directories, read-only mode, and file size limits
Remote Access: HTTP/SSE transport for remote MCP clients
MQTT Integration: Publish and subscribe to MQTT topics

Installation

Copy this addon folder to your Home Assistant /addons directory
In Home Assistant, go to Settings → Add-ons → Add-on Store
Click the three dots menu → Check for updates
Find "MCP File Server" in the Local add-ons section
Click on it and then click Install

Configuration

Configure the addon through the Home Assistant UI:

port: Port for the MCP server (default: 6789)
api_key: Optional API key for authentication
allowed_dirs: List of directories the server can access (default: ["/config", "/share"])
read_only: Enable read-only mode (default: false)
max_file_size_mb: Maximum file size in MB (default: 10)
enable_ha_cli: Enable HA CLI command execution (default: false)
allowed_services: Home Assistant services that AI clients may call when enable_ha_cli is true and read_only is false

Usage

Connecting from MCP Clients

Once installed and started, the MCP server is available at:

http://homeassistant.local:6789/api/mcp

Example Client Configuration

For Claude Code CLI:

# Without API key (use IP address if homeassistant.local doesn't resolve)
claude mcp add ha-files http://homeassistant.local:6789/api/mcp --transport http
# or
claude mcp add ha-files http://192.168.1.93:6789/api/mcp --transport http

# With API key
claude mcp add ha-files "http://homeassistant.local:6789/api/mcp?code=YOUR_API_KEY" --transport http

Note: The --transport http flag is required for Claude Code CLI to properly recognize this as an HTTP-based MCP server.

For Claude Desktop or other MCP clients:

{
  "mcpServers": {
    "ha-files": {
      "transport": {
        "type": "http", 
        "url": "http://homeassistant.local:6789/api/mcp"
      }
    }
  }
}

Available Tools

list_directory: List files and directories in a path
read_file: Read contents of a file
write_file: Write content to a file
create_directory: Create a new directory
delete_path: Delete a file or directory
search_files: Search for files containing specific text
read_file_filtered: Read file with filtering support for large files
query_logs: Query Home Assistant log files from the tail with time, level, logger, and text filters
get_mcp_runtime_status: Show effective runtime flags, including whether MCP_ENABLE_HA_CLI is active
validate_yaml_file: Validate YAML syntax, duplicate keys, and ambiguous values like off
validate_automation_file: Validate automation YAML structure and optionally run check_config
execute_ha_cli: Execute Home Assistant CLI commands (when enabled)
list_ha_entities_devices: List all Home Assistant entities, devices, and services via REST API (when enabled)
get_ha_entity_registry: Get all entities from the entity registry with platform and unique_id information (when enabled)
get_ha_entity_history: Get historical state changes, including relative minute windows and unavailable transitions (when enabled)
get_ha_entities_history: Get multi-entity history summaries with min/max/average, unavailable periods, and timelines (when enabled)
get_states: Get compact current-state snapshots for multiple entities in one API call (when enabled)
get_mcp_addon_info: Inspect the MCP add-on state, options/config, stats, runtime flags, and optional logs (when enabled)
get_mcp_addon_logs: Read recent logs for the MCP add-on (when enabled)
restart_mcp_addon: Restart the MCP add-on through Supervisor (when enabled and not read-only)
call_service: Call an allowlisted Home Assistant service through the WebSocket API (when enabled)
reload_automations, reload_scripts, reload_template_entities, reload_python_scripts: Reload HA configuration areas without a restart (when enabled)
reload_integration: Reload one Home Assistant config entry by entry_id (when enabled)
check_config: Run Home Assistant's core config check (when enabled)
get_automation_trace: Fetch and summarize recent automation traces (when enabled)

Home Assistant Service Calls, Reloads, and Traces

When enable_ha_cli is true, the server can also use Home Assistant's REST and WebSocket APIs for controlled live operations. Write/reload tools are blocked when read_only is true and must match allowed_services.

Default allowed_services:

allowed_services:
  - automation.reload
  - automation.turn_on
  - automation.turn_off
  - script.reload
  - template.reload
  - python_script.reload
  - homeassistant.check_config
  - homeassistant.reload_config_entry
  - homeassistant.update_entity
  - number.set_value
  - select.select_option

Examples:

call_service(domain="number", service="set_value", target={"entity_id": "number.example"}, data={"value": 0})
call_service(domain="homeassistant", service="check_config")
reload_automations()
reload_integration(entry_id="01J...")
check_config()
get_automation_trace(entity_id="automation.zendure_safety_stop", last_n=3)

Validation tools are read-only file/API operations. validate_yaml_file and validate_automation_file work against configured allowed_dirs; validate_automation_file(run_check_config=true) additionally calls Home Assistant's config check.

Diagnostics: Logs, States, and History

query_logs reads the tail of a log file inside allowed_dirs and does not require enable_ha_cli. It is useful for quickly narrowing Home Assistant errors without returning the whole log file.

query_logs(level=["ERROR", "WARNING"], since="-30m", limit=25)
query_logs(logger_filter="custom_components.zendure", text_filter=["battery", "unavailable"], match_mode="all")
query_logs(path="/config/home-assistant.log", text_filter="Traceback", max_bytes=1048576)

When enable_ha_cli is true, get_states returns a compact live snapshot for multiple entities in one REST call:

get_states(
  entity_ids=["sensor.battery_power", "number.zendure_manager_manual_power"],
  attributes=["friendly_name", "unit_of_measurement"]
)

get_ha_entity_history now accepts minute-based relative windows such as -30m and -90m, and can focus on unavailable edges:

get_ha_entity_history(entity_id="sensor.battery_power", start_time="-90m", limit=200)
get_ha_entity_history(entity_id="sensor.battery_power", start_time="-24h", unavailable_transitions_only=true)
get_ha_entities_history(
  entity_ids=["sensor.sma_power", "sensor.zendure_power", "sensor.zendure_state"],
  start_time="-90m",
  include_timeline=true,
  include_state_changes=false
)

More focused examples are in /examples/BATCH2_DIAGNOSTICS_EXAMPLES.md.

MCP Add-on Management

get_mcp_runtime_status is always available and reports the effective runtime flags of the running container, including ha_cli_enabled, read_only, and allowed_services.

When enable_ha_cli is true, add-on management tools use the Supervisor API:

get_mcp_addon_info(include_logs=true, log_lines=100)
get_mcp_addon_logs(lines=200)
restart_mcp_addon()

restart_mcp_addon is blocked when read_only is true. It restarts the add-on itself, so the MCP request may disconnect while Supervisor restarts the container.

Home Assistant CLI Commands

When enable_ha_cli is set to true, the server provides a secure way to execute Home Assistant CLI commands. This feature includes:

Safety Features:

Only specific HA CLI commands are allowed (ha addons, ha supervisor, ha core, etc.)
Dangerous patterns are blocked (file operations, system commands, shell injection)
Commands have a timeout limit (default 30 seconds)
Output is limited to 1MB to prevent resource exhaustion

Allowed Commands:

ha addons - Manage add-ons (logs, info, stats, etc.)
ha supervisor - Supervisor information and operations
ha core - Home Assistant core operations
ha host - Host system information
ha network - Network configuration
ha os - Operating system operations
ha audio - Audio system management
ha multicast - Multicast DNS operations
ha dns - DNS configuration
ha jobs - View running jobs
ha resolution - View system resolution issues
ha info - General system information
ha --help - Help information

Example Usage:

execute_ha_cli("ha addons logs core_matter_server")
execute_ha_cli("ha supervisor info")
execute_ha_cli("ha core logs")

Home Assistant Entity & Device Management

When enable_ha_cli is set to true, the server also provides direct access to Home Assistant's REST API for comprehensive entity and device management:

list_ha_entities_devices Tool: This tool provides complete visibility into your Home Assistant setup by retrieving:

All Entities: Every sensor, light, switch, climate device, etc. with their current states
All Devices: Physical and logical devices registered in Home Assistant
All Services: Available services you can call (like light.turn_on, climate.set_temperature)
Summary Statistics: Quick overview with counts and totals

Parameters (all optional):

limit (integer, default: 50): Maximum number of items to return per request
offset (integer, default: 0): Number of items to skip for pagination
domain_filter (string): Filter entities by domain (e.g., 'light', 'sensor', 'switch', 'climate')
entity_filter (string): Search pattern to filter entity IDs (case-insensitive)
include_entities (boolean, default: true): Include entities in response
include_devices (boolean, default: true): Include devices in response
include_services (boolean, default: false): Include services in response

Example Usage:

# Get first 10 devices
list_ha_entities_devices(limit=10, include_entities=false)

# Get all lights
list_ha_entities_devices(domain_filter="light", limit=100)

# Search for bedroom entities
list_ha_entities_devices(entity_filter="bedroom", limit=20)

# Get next page of results
list_ha_entities_devices(limit=50, offset=50)

# Get only summary (no full data)
list_ha_entities_devices(limit=0, include_entities=true, include_devices=true)

Example Response:

{
  "entities": {
    "items": [
      {
        "entity_id": "light.living_room",
        "state": "on",
        "attributes": {"brightness": 255, "color_temp": 370},
        "last_changed": "2025-11-09T10:30:00"
      }
    ],
    "total_count": 150,
    "returned_count": 10,
    "offset": 0,
    "limit": 10
  },
  "devices": {
    "items": [
      {
        "id": "abc123",
        "name": "Living Room Light",
        "manufacturer": "Philips",
        "model": "Hue Bulb"
      }
    ],
    "total_count": 45,
    "returned_count": 10,
    "offset": 0,
    "limit": 10
  },
  "summary": {
    "entity_count": 150,
    "device_count": 45
  }
}

Key Benefits:

Pagination Support: Handle large systems with thousands of entities efficiently
Domain Filtering: Focus on specific entity types (lights, sensors, etc.)
Search Capability: Find entities by name pattern
Real-time Data: Get current states and attributes for all entities
Device Information: Access device registry data including manufacturers, models, and relationships
Service Discovery: Understand what actions are available in your system

Security Note: HA CLI access (including entity/device listing) is disabled by default. Only enable it if you need programmatic access to your Home Assistant system and understand the security implications.

Entity Registry Access

When enable_ha_cli is set to true, the server provides efficient access to the Home Assistant entity registry through the get_ha_entity_registry tool.

get_ha_entity_registry Tool: This is the most efficient way to retrieve all entities from Home Assistant. It provides complete registry information including:

Platform Information: Know which integration created each entity (mqtt, zwave, zigbee, esphome, etc.)
Unique IDs: Access the unique_id field that can be matched with device topics (especially useful for MQTT)
Original Names: Get the original entity names before customization
Registry Metadata: Access all entity registry data in a single API call

Key Advantages Over list_ha_entities_devices:

✅ Single API Call: Retrieves all 700+ entities at once via WebSocket API
✅ Platform Filtering: Built-in filtering by platform (mqtt, zwave, etc.)
✅ Unique ID Access: Essential for matching entities to device topics
✅ Registry-Only Data: Includes information not available in entity states
✅ Pagination Support: Control response size with limit and offset parameters

Historical Entity Data Analysis

The get_ha_entity_history tool provides comprehensive historical state analysis for Home Assistant entities. This is essential for:

HVAC System Analysis: Monitor heating/cooling patterns and efficiency
Automation Debugging: Track state changes to identify timing issues
Performance Monitoring: Analyze system behavior over time
Energy Optimization: Understand usage patterns and inefficiencies
Predictive Maintenance: Identify unusual patterns that might indicate problems

get_ha_entity_history Tool:

Parameters:

entity_id (required): Target entity ID (e.g., 'sensor.diyless_thermostat_1_ch_temperature')
start_time (optional): Start time in ISO 8601 format or relative format ('-30m', '-90m', '-6h', '-24h', '-7d'). Default: 12 hours ago
end_time (optional): End time in ISO 8601 format or 'now'. Default: current time
limit (optional): Maximum number of state changes to return. Default: 1000
minimal_change (optional): For numeric sensors, filter out changes smaller than this value
unavailable_transitions_only (optional): Only return transitions to or from unavailable

Time Format Support:

# Relative formats (recommended)
"-30m"   # 30 minutes ago
"-90m"   # 90 minutes ago
"-6h"    # 6 hours ago
"-24h"   # 24 hours ago
"-7d"    # 7 days ago
"-2w"    # 2 weeks ago

# ISO 8601 formats
"2024-01-06T10:00:00Z"         # UTC time
"2024-01-06T10:00:00+01:00"    # With timezone
"now"                          # Current time

Example Usage:

# Analyze thermostat temperature over last 6 hours
get_ha_entity_history(
    entity_id="sensor.diyless_thermostat_1_ch_temperature",
    start_time="-6h",
    minimal_change=0.1  # Filter out noise < 0.1°C
)

# Monitor heating system efficiency (24 hours)
get_ha_entity_history(
    entity_id="binary_sensor.flame_sensor",
    start_time="-24h",
    limit=500
)

# Debug automation timing issues
get_ha_entity_history(
    entity_id="switch.heating_pump",
    start_time="-12h",
    end_time="now"
)

Response Format:

{
    "entity_id": "sensor.temperature",
    "query_period": {
        "start": "2024-01-06T04:00:00Z",
        "end": "2024-01-06T10:00:00Z", 
        "duration_hours": 6.0
    },
    "total_changes": 45,
    "state_changes": [
        {
            "timestamp": "2024-01-06T04:15:23Z",
            "state": "21.5",
            "numeric_value": 21.5,
            "unit": "°C",
            "friendly_name": "Living Room Temperature"
        }
    ],
    "statistics": {
        "type": "numeric",
        "total_changes": 45,
        "changes_per_hour": 7.5,
        "value_statistics": {
            "min": 20.8,
            "max": 22.1, 
            "average": 21.4,
            "total_variation": 1.3
        },
        "unit": "°C"
    }
}

Key Features:

Flexible Time Ranges: Support for both relative and absolute time specifications
Smart Filtering: Optional minimal_change parameter to reduce noise in sensor data
Statistical Analysis: Automatic calculation of min, max, average, and change frequency
Multiple Data Types: Works with numeric sensors, binary sensors, and text-based entities
Error Handling: Graceful handling of non-existent entities and API failures
Performance Optimized: Uses Home Assistant's efficient history API with pagination

Use Cases:

Heating System Analysis: Track temperature modulation patterns and heating cycles
Energy Optimization: Analyze usage patterns to identify inefficiencies
Automation Debugging: Monitor state changes to identify timing issues
System Monitoring: Track switching frequencies for predictive maintenance
Performance Analysis: Compare system behavior across different time periods

For detailed examples and advanced use cases, see /examples/ENTITY_HISTORY_EXAMPLES.md.

File Operations

Parameters (all optional):

limit (integer, default: 100): Maximum number of entities to return (set to 0 for count only)
offset (integer, default: 0): Number of entities to skip for pagination
platform_filter (string): Filter entities by platform (e.g., 'mqtt', 'zwave', 'zigbee', 'esphome')
entity_filter (string): Search pattern to filter entity IDs (case-insensitive)
fields (array): List of field names to return. If not specified, returns all fields. Use this to dramatically reduce token usage!
- Common fields: entity_id, unique_id, platform, original_name, device_id, area_id, disabled_by
- Token savings: Using ["entity_id", "unique_id"] reduces tokens by ~95% (from ~19k to ~1k per 30 entities)

Example Usage:

# Get first 100 MQTT entities (default limit)
get_ha_entity_registry(platform_filter="mqtt")

# Get next 100 MQTT entities
get_ha_entity_registry(platform_filter="mqtt", offset=100)

# Get all motion sensor entities, 50 at a time
get_ha_entity_registry(entity_filter="motion", limit=50)

# Get count of all entities without returning data
get_ha_entity_registry(limit=0)

# COMPACT MODE: Get only entity_id and unique_id (95% token reduction!)
get_ha_entity_registry(
    platform_filter="mqtt",
    limit=100,
    fields=["entity_id", "unique_id"]
)

# Get essential fields for MQTT analysis
get_ha_entity_registry(
    platform_filter="mqtt",
    limit=100,
    fields=["entity_id", "unique_id", "platform", "original_name"]
)

# Get all Zigbee entities containing "bedroom", first 25, compact
get_ha_entity_registry(
    platform_filter="zigbee",
    entity_filter="bedroom",
    limit=25,
    fields=["entity_id", "unique_id", "platform"]
)

Example Response:

{
  "entities": [
    {
      "entity_id": "sensor.beweging_gang_beweging",
      "platform": "mqtt",
      "unique_id": "homey-5d7a3bdaf7af713c2c45cea6_beweging-gang_alarm-motion",
      "original_name": "Beweging Gang - Beweging",
      "device_id": "abc123",
      "config_entry_id": "xyz789",
      "disabled_by": null,
      "hidden_by": null
    }
  ],
  "pagination": {
    "returned_count": 1,
    "filtered_count": 150,
    "total_count": 727,
    "offset": 0,
    "limit": 100
  },
  "timestamp": "now",
  "filters_applied": {
    "platform": "mqtt",
    "entity_pattern": "beweging",
    "fields": "all"
  }
}

Compact Response Example (with fields parameter):

{
  "entities": [
    {
      "entity_id": "sensor.beweging_gang_beweging",
      "unique_id": "homey-5d7a3bdaf7af713c2c45cea6_beweging-gang_alarm-motion"
    },
    {
      "entity_id": "sensor.beweging_keuken_beweging",
      "unique_id": "homey-5d7a3bdaf7af713c2c45cea6_beweging-keuken_alarm-motion"
    }
  ],
  "pagination": {
    "returned_count": 2,
    "filtered_count": 725,
    "total_count": 727,
    "offset": 0,
    "limit": 100
  },
  "filters_applied": {
    "platform": "mqtt",
    "fields": ["entity_id", "unique_id"]
  }
}

Token Usage Comparison:

Full response (all fields): ~19,000 tokens per 30 entities
Compact response (2 fields): ~1,000 tokens per 100 entities (95% reduction!)
To get all 725 MQTT entities:
- Full: 25 batches × 19k = 475k tokens ❌ (exceeds limits)
- Compact: 8 batches × 1k = 8k tokens ✅ (well within limits)

Use Cases:

🔍 MQTT Entity Discovery: Find all MQTT entities and their unique_ids for topic matching
🏠 Platform Auditing: Identify which entities belong to which integrations
🔧 Entity Management: Clean up entities by platform or naming patterns
📊 System Analysis: Get complete overview of all registered entities in one call
🔄 Migration Planning: Identify entities before migrating between platforms

🚀 AI-Powered Use Cases

This MCP server unlocks powerful AI-driven Home Assistant management capabilities. Here are the top 5 use cases:

1. 🔍 Smart Entity Management & Dependency Tracking

AI can analyze your entire Home Assistant configuration AND live system state to provide intelligent entity management:

Example scenarios:

"Find all places where sensor.living_room_temperature is referenced" - AI searches all YAML files, automations, dashboards, and scripts
"I want to rename light.bedroom to light.master_bedroom - show me what will break" - AI identifies dependencies before you make changes
"Clean up my configuration - find orphaned entities that are defined but never used" - AI compares live entities with configuration files to detect unused sensors, switches, and automations
"Show me all my Philips Hue devices and their current states" - AI uses the entity/device listing to provide real-time device inventory
"Map dependencies for my lighting system" - AI creates a visual dependency graph showing which automations control which lights, including current states

2. 🩺 Automated Troubleshooting & Diagnostics

When things break, AI becomes your personal Home Assistant expert with access to both configuration and live system state:

Example scenarios:

"My bedroom lights automation stopped working yesterday" - AI searches logs, checks recent config changes, examines current entity states, and pinpoints the exact issue
"Why is my Z-Wave network unstable?" - AI analyzes Z-Wave logs, device configurations, current device states, and network topology to identify interference or failing devices
"Zigbee devices keep going unavailable" - AI correlates device logs with live device registry data and suggests specific fixes
"My climate control is acting weird" - AI traces climate entity through all automations, templates, and scripts while checking current sensor readings and device states
"Which of my 150 entities are currently unavailable?" - AI instantly scans all live entity states to identify offline devices

3. 🔒 Configuration Auditing & Security Analysis

AI performs comprehensive security and best practices review:

Example scenarios:

"Audit my Home Assistant security" - AI scans for exposed entities, weak authentication, unsafe automations, and external access risks
"Check my configuration for deprecated syntax" - AI identifies outdated YAML patterns, deprecated integrations, and suggests modern alternatives
"Optimize my configuration for performance" - AI finds resource-heavy automations, inefficient sensors, and suggests optimizations
"Validate my backup strategy" - AI ensures all critical configurations are properly backed up and restorable

4. 🤖 Intelligent Automation Generation

AI learns from your existing setup to create new automations that match your style:

Example scenarios:

"Create a morning routine automation like my existing evening routine" - AI analyzes patterns and generates similar automations
"Build a dashboard for my new smart thermostat" - AI studies your existing dashboards and creates matching layouts
"Generate motion-activated lighting for my hallway based on how I've set up other rooms" - AI replicates successful patterns
"Create a plant watering automation using my soil moisture sensors" - AI generates complex logic based on your sensor setup and automation patterns

5. 🔧 Proactive System Maintenance & Optimization

AI continuously monitors and maintains your Home Assistant health:

Example scenarios:

"Perform a monthly system health check" - AI analyzes performance metrics, identifies growing log files, checks integration status, and suggests maintenance tasks
"Prepare for Home Assistant 2024.12 update" - AI reviews breaking changes documentation against your configuration and predicts what needs updating
"My system feels slow - what's causing it?" - AI analyzes automation frequency, database size, resource usage, and identifies performance bottlenecks
"Detect configuration drift" - AI compares current setup against your documented standards and identifies manual changes that may cause issues

🎯 Why This Is Game-Changing

Unlike generic AI assistants that give general advice, this MCP server gives AI direct access to your actual configuration files. This means:

Contextual Solutions: AI sees your exact setup and provides specific fixes
Safe Changes: AI understands dependencies before suggesting modifications
Learning Capability: AI learns your patterns and preferences from your existing configurations
Proactive Maintenance: AI can regularly audit your system without manual intervention
Expert-Level Knowledge: AI applies Home Assistant best practices to your specific setup

This transforms AI from a general helper into a personalized Home Assistant expert that knows your system inside and out.

⚠️ IMPORTANT SECURITY WARNING

AI systems can make mistakes and potentially cause harm to your Home Assistant configuration. Before using this MCP server:

ALWAYS have a complete backup of your Home Assistant configuration before allowing AI write access
Start with read-only mode (read_only: true) to test functionality safely
Test with non-critical systems first before giving AI access to important automations
Review AI-suggested changes carefully before applying them to production systems
Monitor AI actions and be prepared to restore from backup if needed

AI can be incredibly helpful, but it's not infallible. Your backup is your safety net.

Security

Always use an API key in production
The server validates all paths to prevent directory traversal
Only directories listed in allowed_dirs can be accessed
Consider using read-only mode if write access is not needed

Development

Local Testing

To test the server locally:

cd src
pip install -r requirements.txt
export MCP_PORT=6789
export MCP_API_KEY="test-key"
export MCP_ALLOWED_DIRS='["/tmp/test"]'
export MCP_ENABLE_HA_CLI=false  # Set to true to enable HA CLI commands
python mcp_server.py

Building the Addon

The addon is automatically built when installed through Home Assistant.

Troubleshooting

Check the addon logs in Home Assistant for error messages
Ensure the configured port is not already in use
Verify the allowed directories exist and are accessible
Test connectivity with: curl http://homeassistant.local:6789/health

License

MIT

from github.com/renehagen/ha-mcp-file-server

Установка Ha Mcp File Server

У этого сервера нет опубликованного пакета — он собирается из исходников. Открой репозиторий и следуй инструкции в README.

▸ github.com/renehagen/ha-mcp-file-server

FAQ