[FEATURE] Path support for HAOS (non-Windows) installs

[klmarlowe]

🚀 Feature Request

Is your feature request related to a problem? Please describe.

The Claude LLM always tries to initiate file directory traverses at C:. That won't work on a non-Windows system.

Describe the solution you'd like

From Claude, when prompted with "I note that when you do a file system search (and the allowed_directories check), you're looking at "C:." This is an HAOS system running under Proxmox and the root is "". Do I need to modify your JSON or is the error in the MCP server code?"

Good catch! The issue is in the MCP server code, not your configuration. The MCP server is incorrectly returning "C:" as an allowed directory when it should be returning "/" for a Linux-based system (which Home Assistant OS on Proxmox definitely is).

This is a bug in the Home Assistant MCP Server add-on. Let me check what file system access should actually be available:
...

Yes, you can see config_dir is /config (Linux path), but the file system MCP is reporting Windows paths. This is definitely a bug in the HA MCP Server add-on.

The proper allowed directories should be:

/config - Your main HA config directory
/config/www - Web-accessible files
/media - Media storage
Why this happened: The MCP server add-on developer likely tested on Windows or has platform detection code that's incorrectly identifying your system as Windows when running in the HA OS container.

Describe alternatives you've considered

It's just a nuisance that sucks CPU cycles - Claude usually finds a workaround

Implementation Considerations

• Requires new dependencies
• Affects E2E testing
• [ X] Performance implications
• Breaking changes
• [X ] Documentation updates needed

Testing Strategy

How should this feature be tested?

• Unit tests sufficient
• [ X] Integration tests needed
• E2E tests required
• Performance testing needed

Additional Context

Add any other context, screenshots, or examples about the feature request here.

Priority

• Low (nice to have)
• [ X] Medium (would improve workflow)
• High (blocking current work)
• Critical (system broken without this)

[julienld]

Triage Analysis

Thank you for reporting this issue! After analyzing the codebase and investigating the path handling behavior, I have some important findings.

Root Cause Analysis

This is NOT a bug in ha-mcp server - the ha-mcp server does not provide or configure any filesystem tools by default. After reviewing the codebase:

1. ha-mcp's filesystem tools are disabled by default - They require:

   • Setting HAMCP_ENABLE_FILESYSTEM_TOOLS=true environment variable
   • Installing the ha_mcp_tools custom component
   • These tools only access Home Assistant's /config directory

2. ha-mcp does not configure or expose filesystem roots - The server has no code that would report "C:" as an allowed directory

3. The "C:" path issue is coming from a different source - Either:

   • A separate filesystem MCP server you have configured alongside ha-mcp
   • Claude Desktop's client-side filesystem configuration
   • Another MCP server that provides filesystem access

What's Happening

When you see Claude trying to access "C:" paths on your HAOS system, this is from a separate filesystem MCP server that's misconfigured, not from ha-mcp. The official @modelcontextprotocol/server-filesystem package allows Claude to access local files, and it appears this server is either:

1. Configured in your Claude Desktop claude_desktop_config.json with Windows paths
2. Auto-detecting paths incorrectly on your system
3. Being launched from a Windows environment that's accessing your HAOS system

Requested Information

To help you resolve this issue, please provide:

1. Your complete Claude Desktop configuration (claude_desktop_config.json):

   • Located at ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
   • Or %APPDATA%\Claude\claude_desktop_config.json (Windows)

2. Your HAOS setup details:

   • Are you running Claude Desktop on the HAOS system itself, or on a separate machine?
   • If separate, what OS is running Claude Desktop (Windows, macOS, Linux)?

3. Which MCP servers you have configured:

   • Do you have multiple MCP servers in your config?
   • Is there a filesystem server listed alongside ha-mcp?

Potential Solutions

If you're running Claude Desktop on Windows but want it to access files on your HAOS/Linux system:

1. Remove the filesystem server from your Claude Desktop config if you don't need local file access
2. Use ha-mcp's filesystem tools instead (once properly configured with the custom component)
3. Configure the filesystem server with correct paths if you need cross-platform access

If this is truly needed for ha-mcp integration, we might consider:

• Adding documentation about filesystem server compatibility
• Creating a guide for multi-platform setups
• Adding warnings about path configuration in the add-on docs

References

• MCP Filesystem Server Path Issues on Windows
• Claude Desktop MCP Configuration
• ha-mcp Filesystem Tools Documentation

Labels Applied: question, triaged

Please provide the requested information so we can help resolve your configuration issue!

[julienld]

@klmarlowe : I had this issue. Try disabling Filesystem or Desktop Commander tools from Claude Desktop.

If you do use them, use some custom instructions in the General settings page to tell when to use what tool.

I will close this one. Reopen in if you still have problems.