Troubleshooting

Common Issues

Server Not Showing in Claude Desktop

1. Check config file path is correct

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Verify executable path is absolute (not relative)

   • Correct: C:\\Tools\\filesystem-ultra.exe
   • Incorrect: .\filesystem-ultra.exe

3. Check Claude Desktop logs

   • Windows: %APPDATA%\Claude\logs\
   • Look for MCP-related errors

4. Validate JSON syntax

   • Use a JSON validator
   • Common issue: missing commas or trailing commas

”Access Denied” Errors

• Ensure paths are in allowed paths (positional arguments or --allowed-paths)
• Check Windows file permissions
• Verify paths exist and are accessible
• Run Claude Desktop as administrator (if needed)

Slow Performance

• Increase --cache-size (try 500MB)
• Increase --parallel-ops (try 16)
• Enable --compact-mode to reduce overhead
• Check if antivirus is scanning files

High Memory Usage

• Reduce --cache-size
• Reduce --parallel-ops
• Large cache sizes increase memory usage proportionally

Timeouts on Large Files

• Use intelligent tools (intelligent_read, intelligent_write)
• These automatically select the best strategy for file size
• For very large files (more than 5MB), use streaming tools

Edit Operations Failing

• Verify old_text matches exactly (including whitespace)
• Use recovery_edit for fuzzy matching
• Check file encoding (UTF-8 recommended)

Backup Directory Issues

• Ensure backup directory is in allowed paths
• Verify write permissions to backup location
• Check available disk space

WSL Path Issues

• When building for Windows from WSL, use GOOS=windows
• Paths like C:\... should work on Windows builds
• Paths like /mnt/c/... work in WSL builds

Diagnostic Commands

Test your installation with these commands in Claude Desktop:

Show me the performance stats

Expected output shows operations per second, cache hit rate, and memory usage.

List the contents of [allowed path]

Should return directory listing without errors.

Log Levels

Use --log-level to control verbosity:

Level	Description
error	Only errors (recommended for production)
warn	Errors and warnings
info	Standard logging
debug	Verbose debugging information

Need More Help?

• Check the full documentation
• Report issues at GitHub Issues
• Include logs and configuration when reporting issues