Quick Start

Get up and running with MCP Filesystem Ultra in just a few steps.

Prerequisites

• Go 1.26+ installed (download here)
• Windows, Linux, or WSL environment
• Claude Desktop installed (optional, but recommended)

Step 1: Clone or Download

git clone https://github.com/scopweb/mcp-filesystem-go-ultra.git
cd mcp-filesystem-go-ultra

Step 2: Build

Windows (Recommended - Use Build Script)

build.bat

Manual Build

go mod tidy
go build -ldflags="-s -w" -trimpath -o filesystem-ultra.exe .

This creates an optimized executable (approximately 8.8 MB).

Step 3: Test Run

# Show version
./filesystem-ultra.exe --version

# Output: MCP Filesystem Ultra v4.0.0

Step 4: Configure Claude Desktop

Edit your Claude Desktop configuration file:

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

Add this configuration:

{
  "mcpServers": {
    "filesystem-ultra": {
      "command": "C:\\path\\to\\filesystem-ultra.exe",
      "args": [
        "--compact-mode",
        "--cache-size", "200MB",
        "--parallel-ops", "8",
        "--log-level", "error",
        "C:\\your\\project\\path\\"
      ]
    }
  }
}

Token Optimization

The --compact-mode flag reduces token usage by 65-75%.

Step 5: Restart Claude Desktop

1. Completely quit Claude Desktop
2. Start it again
3. Look for the hammer icon indicating MCP tools are available

Step 6: Test It Out

In Claude Desktop, try:

Can you list the files in my project directory?

Claude should now use the list_directory tool from your MCP server.

Verify Installation

Check that the server is working:

Can you show me the performance stats of the filesystem server?

You should see output like:

Performance Statistics
Total operations: 45
Operations/sec: 2016.0
Cache hit rate: 98.9%
Memory usage: 40.3 MB

Configuration Options

Minimal Token Usage

{
  "args": [
    "--compact-mode",
    "--max-response-size", "5MB",
    "--max-search-results", "50",
    "--max-list-items", "100",
    "--log-level", "error",
    "--cache-size", "200MB",
    "--parallel-ops", "8",
    "C:\\allowed\\path\\"
  ]
}

Token savings: approximately 92.7% in typical sessions

Balanced (More Detail)

{
  "args": [
    "--compact-mode",
    "--max-response-size", "10MB",
    "--max-search-results", "200",
    "--log-level", "info",
    "--cache-size", "200MB",
    "C:\\allowed\\path\\"
  ]
}

Token savings: approximately 50-60%

Verbose (Maximum Detail)

{
  "args": [
    "--cache-size", "200MB",
    "--parallel-ops", "8",
    "--log-level", "info",
    "C:\\allowed\\path\\"
  ]
}

No token optimization - full details with formatting.

Common Flags

Flag	Description	Default
--compact-mode	Minimal responses (65-75% token savings)	false
--cache-size	Memory cache size	100MB
--parallel-ops	Max concurrent operations	2x CPU cores
--log-level	Logging level (debug, info, warn, error)	info
--allowed-paths	Comma-separated paths to restrict access	None (all paths)
--backup-dir	Directory for backups	temp/mcp-backups

Security: Restrict Access

Important

By default, the server has access to ALL filesystem paths. Always use --allowed-paths or positional arguments to restrict access.

{
  "args": [
    "--compact-mode",
    "C:\\Projects\\",
    "C:\\Documents\\"
  ]
}

Now the server can ONLY access paths under C:\Projects\ and C:\Documents\.

Troubleshooting

Server not showing in Claude Desktop

1. Check the config file path is correct
2. Verify the executable path is absolute (not relative)
3. Look at Claude Desktop logs: %APPDATA%\Claude\logs\

”Access denied” errors

• Ensure paths in args are accessible
• Check --allowed-paths is not too restrictive
• Verify file permissions

Slow performance

• Increase --cache-size (try 500MB)
• Increase --parallel-ops (try 16)
• Enable --compact-mode to reduce overhead

Next Steps

Now that you are up and running:

• Learn about Intelligent Operations - The auto-optimization system
• Explore the API - All 16 available tools
• Configure Backups - Protect against mistakes
• Set up Hooks - Auto-format, validate, and more

Need Help?

• Check the Troubleshooting Guide
• Read Claude Instructions for best practices
• Report issues on GitHub