MCP Filesystem Server Ultra-Fast
scopweb/mcp-filesystem-go-ultra
Servidor filesystem ultrarrápido em Go com 17 tools, pipeline e auditoria
Ver no GitHubServidor MCP de alta performance em Go para manipulação de arquivos com 17 ferramentas consolidadas, sistema de pipeline, auditoria, dashboard e suporte a WSL. Otimizado para Claude Desktop e Claude Code com cache inteligente, edição segura com rollback e operações em lote atômicas.
Instalação
npx convez-ai scopweb/mcp-filesystem-go-ultra1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Manipulação eficiente de grandes projetos com centenas de arquivos
- Automação de operações em lote com pipeline DAG e dry-run
- Desenvolvimento seguro com backup automático, avaliação de risco e rollback
- Operações cross-platform WSL/Windows com tradução transparente de caminhos
- Auditoria e observabilidade com logging JSON Lines e dashboard em tempo real
Veredito

Ferramenta técnica sólida e bem-engineered para gerenciamento de filesystem em escala, com cache de 3 camadas, pipeline paralelo e auditoria completa. Ideal para fluxos automatizados complexos, porém requer Go 1.26+ e curva de aprendizado para explorar todo o potencial do sistema.
README
A tradução para o português deste README ainda está na fila.
MCP Filesystem Server Ultra-Fast
v4.5.2 · Go · MCP 2025-11-25 · 17 core tools + git + help + fs super-tool
A high-performance Model Context Protocol filesystem server written in Go. Designed for use with Claude Desktop and Claude Code, with first-class support for large files, WSL/Windows interoperability, and token-efficient responses.
Features
- 17 core tools + git + help (consolidated from 59 in v3.x) — all functionality preserved, zero tool bloat
- 31 tools total (16 core + 13 aliases) with Claude Code-compatible names (View, Edit, Write, LS, GlobTool, GrepTool, etc.)
- MCP spec-compliant annotations —
readOnlyHint,destructiveHint,idempotentHinton every tool - Intelligent editing with automatic backup, risk assessment, and rollback on failure
- 3-tier cache (BigCache + go-cache) with file watcher invalidation for O(1) reads
- Streaming and chunked I/O for files up to 50 MB without blocking
- WSL ↔ Windows path translation — accepts
/mnt/c/...,C:\..., and/tmp/...transparently - Compact mode — minimal token responses (~90% reduction) for high-volume Claude Desktop sessions
- Risk assessment — edits above configurable thresholds (30 / 50 / 90% change) require explicit confirmation
- Hook system — pre/post hooks for write, edit, delete, create, move, and copy events
- Plan mode — dry-run analysis with diff preview and risk report before applying changes
- Pipeline system — 12 actions with conditions, templates, DAG-based parallel execution (5–22× fewer round-trips)
- Atomic batch operations — grouped file operations with rollback on failure
- Audit logging — JSON Lines operation log + metrics snapshots for observability
- Dashboard — separate HTTP binary for real-time metrics, operation log, and backup recovery
- Access control — restrict the server to specific directory trees via
--allowed-paths
Build
# Build (Windows) — v4 binary
go build -ldflags="-s -w" -trimpath -o filesystem-ultra-v4.exe .
# With ripgrep embedded (~4MB larger)
go build -ldflags="-s -w" -trimpath -tags embed_rg -o filesystem-ultra-v4-embed.exe .
# Or use the build scripts
build-windows.bat # default
build-windows-embed.bat # with ripgrep
Requires Go 1.26+. No CGO. Tested on Windows 11 and Ubuntu 22.04 (WSL2).
# Run tests
go test ./tests/... ./core/...
# With race detector
go test -race ./...
# Security fuzzing
go test -fuzz=Fuzz ./tests/security
Configuration
Add to your claude_desktop_config.json:
{
"mcpServers": {
"filesystem": {
"command": "C:\\path\\to\\filesystem-ultra-v4.exe",
"args": [
"--compact-mode",
"--cache-size", "200MB",
"--parallel-ops", "8",
"--log-level", "error",
"--log-dir", "C:\\logs\\mcp-filesystem",
"C:\\your\\project\\"
]
}
}
}
Linux:
{
"mcpServers": {
"filesystem-ultra": {
"command": "/path/to/filesystem-ultra",
"args": [
"--compact-mode",
"--cache-size", "200MB",
"--parallel-ops", "8",
"--log-level", "error",
"--log-dir", "/home/user/.local/share/mcp-filesystem/logs",
"/home/user/projects/"
]
}
}
}
The positional arguments after the flags are the allowed base paths. Omitting paths disables access control entirely.
Key flags
| Flag | Default | Description |
|---|---|---|
--compact-mode | off | Minimal token responses |
--cache-size | 100MB | In-memory file cache limit |
--parallel-ops | 2×CPU (max 16) | Max concurrent operations |
--backup-dir | system temp | Directory for automatic backups |
--backup-max-age | 72h | Maximum backup retention |
--backup-max-count | 50 | Maximum backup count per file |
--risk-threshold-medium | 30 | % change that triggers a warning |
--risk-threshold-high | 50 | % change that requires force: true |
--hooks-enabled | off | Enable pre/post operation hooks |
--hooks-config | — | Path to hooks configuration JSON |
--log-dir | — | Directory for audit logs and metrics (enables logging) |
--log-level | info | Log level: debug, info, warn, error |
--debug | off | Verbose debug logging |
Tool Discovery
Claude Desktop uses lazy tool loading — it only discovers ~5 tools per query via semantic search, missing most of the 16 available tools.
Three layers solve this:
| Layer | How it works | Client support |
|---|---|---|
/filesystem-ultra-tools skill | Claude Code skill that calls help on conversation start | Claude Code |
help tool | Keyword-rich description; returns full 16-tool catalog | Any MCP client |
fs super-tool | Single entry point dispatching to all 16 operations via action param | Any MCP client |
server.WithInstructions() | Sends catalog during MCP initialize handshake | Spec-compliant clients |
Using the skill
The skill ships in .claude/skills/filesystem-ultra-tools/. In Claude Code or Claude Desktop, invoke:
/filesystem-ultra-tools
This calls the help tool and loads the full catalog. You can also add this to your project instructions:
At the start of every conversation, do tool_search for "filesystem help" and then call filesystem-ultra:help()
Available Tools (16 + 6 aliases + fs + help)
Core (5)
| Tool | Description |
|---|---|
read_file | Read full file, line range (start_line/end_line), head/tail (max_lines+mode), or base64 (encoding:"base64") |
write_file | Create or overwrite file. Supports text (content) and binary (encoding:"base64") |
edit_file | Find-and-replace with backup and risk assessment. Modes: exact match (default), search_replace (all occurrences), regex (capture groups), occurrence:N (Nth match) |
list_directory | Directory listing with cache |
search_files | Search by pattern with optional file_types, include_content, include_context, case_sensitive, count_only |
Edit+ (1)
| Tool | Description |
|---|---|
multi_edit | Multiple find-and-replace operations on the same file in one call via edits_json |
File Operations (4)
| Tool | Description |
|---|---|
move_file | Move or rename file/directory |
copy_file | Recursive copy preserving permissions |
delete_file | Soft-delete (default) or permanent (permanent: true) |
create_directory | Create directory tree (mkdir -p) |
Batch & Pipeline (1)
| Tool | Description |
|---|---|
batch_operations | Atomic batch ops (request_json), multi-step pipelines (pipeline_json), or batch rename (rename_json) — with rollback on failure |
Backup (1)
| Tool | Description |
|---|---|
backup | Manage backups via action: list, info, compare, cleanup, restore |
Analysis (1)
| Tool | Description |
|---|---|
analyze_operation | Dry-run preview via operation: file, edit, delete, write, optimize, compare |
WSL (1)
| Tool | Description |
|---|---|
wsl | WSL ↔ Windows sync and status. Params: wsl_path/windows_path + direction, or action:"status" |
Utility (1)
| Tool | Description |
|---|---|
server_info | Server diagnostics via action: stats, help, artifact |
Info (1)
| Tool | Description |
|---|---|
get_file_info | Size, permissions, timestamps, type |
Dashboard
Separate binary for real-time observability — reads audit logs and serves a web UI.
# Build
go build -ldflags="-s -w" -trimpath -o dashboard.exe ./cmd/dashboard/
# Run
dashboard.exe --log-dir=C:\logs\mcp-filesystem --backup-dir=C:\backups --port=9100
- No coupling with MCP server (file-based communication only)
- Embedded web assets via
go:embed(single binary, no dependencies) - Real-time updates via SSE (Server-Sent Events)
- Pages: Dashboard (metrics), Operations (audit log), Backups (enterprise recovery), Statistics, Proxy/Tokens, Edit Analysis
MCP Proxy
Transparent stdio proxy that logs every tool call with timing and token estimates. Sits between Claude Desktop and the MCP server.
# Build
go build -ldflags="-s -w" -trimpath -o mcp-proxy.exe ./cmd/proxy/
# Claude Desktop config — wrap the MCP server with the proxy
# "command": "mcp-proxy.exe",
# "args": ["--model", "sonnet-4", "--log-dir", "C:\\logs\\mcp-proxy", "--", "filesystem-ultra-v4.exe", ...]
Point the dashboard at the proxy logs to see the Proxy / Tokens page:
dashboard.exe --log-dir=C:\logs\mcp-filesystem --proxy-log-dir=C:\logs\mcp-proxy --port=9100
See docs/setup/DASHBOARD_PROXY_SETUP.md for full setup guide.
Audit Logging
When --log-dir is set on the MCP server, it writes:
operations.jsonl— JSON Lines audit log (one entry per tool call, auto-rotates at 10MB)metrics.json— Performance metrics snapshot (updated every 30 seconds)
Architecture
main.go Entry point — config, CLI flags, server startup (~250 lines)
audit.go auditWrap — request normalization + audit logging
format.go Response formatters, parseSize, truncateContent, formatSize
help_content.go getHelpContent() — static help text for all topics
tools_core.go toolRegistry, registerTools, read_file/write_file/edit_file
tools_search.go list_directory, search_files, analyze_operation
tools_files.go create_directory, delete_file, move_file, copy_file, get_file_info
tools_batch.go multi_edit, batch_operations, backup
tools_platform.go wsl, server_info
tools_aliases.go 6 aliases, fs super-tool, help tool
core/
engine.go UltraFastEngine — central struct, cache, worker pool, metrics
edit_operations.go EditFile, MultiEdit — backup, risk assessment, hooks
file_operations.go Rename, SoftDelete, Copy, Move
streaming_operations.go StreamingWrite, ChunkedRead, SmartEdit
search_operations.go SmartSearch, AdvancedTextSearch
backup_manager.go Create, restore, compare, and clean backups
impact_analyzer.go Risk assessment (LOW / MEDIUM / HIGH / CRITICAL)
edit_safety_layer.go Context validation, stale-edit prevention
hooks.go Pre/post hook system (12 event types)
large_file_processor.go Line-by-line and chunk-based processing
regex_transformer.go Regex transformations with capture groups
pipeline.go Multi-step pipeline execution (sequential + parallel)
pipeline_types.go Pipeline types, validation
pipeline_conditions.go 9 condition types for conditional steps
pipeline_templates.go {{step_id.field}} template resolution
pipeline_scheduler.go DAG builder, topological sort, destructive step splitting
batch_operations.go Atomic batch operations with rollback
batch_rename.go Batch file renaming
audit_logger.go JSON Lines operation log + MetricsSnapshot writer
claude_optimizer.go Claude Desktop auto-optimization (small/large file strategy)
plan_mode.go Dry-run analysis (analyze_write, analyze_edit, analyze_delete)
path_converter.go WSL ↔ Windows path conversion
path_detector.go Path format detection and WSL distro lookup
wsl_sync.go WSL/Windows file synchronization
autosync_config.go Auto-sync configuration system
watcher.go File watcher for cache invalidation
mmap.go Memory-mapped file I/O (Windows fallback)
config.go Thresholds and constants
errors.go PathError, ValidationError, EditError, PipelineStepError, etc.
cache/
intelligent.go BigCache (files) + go-cache (dirs + metadata)
cmd/
proxy/
main.go Stdio proxy — logs tool calls, timing, token estimates
dashboard/
main.go HTTP dashboard for logs/metrics/backups
static/ Embedded web UI (go:embed)
tests/
mcp_functions_test.go Core MCP function tests
bug5_test.go–bug9_test.go Regression tests
edit_safety_test.go Edit safety validation tests
security/ Security & fuzzing tests
File size thresholds
| Class | Size | Strategy |
|---|---|---|
| Small | < 100 KB | Direct I/O |
| Medium | < 500 KB | Streaming |
| Large | < 5 MB | Chunking |
| Very large | < 50 MB | Special handling |
| Over limit | ≥ 50 MB | Edit rejected |
Security
IsPathAllowed()resolves symlinks viafilepath.EvalSymlinks()before containment check — prevents symlink escape from allowed paths- Allowed-path root protection (v4.2.1) —
delete_file,soft_delete, andmove_filereject the--allowed-pathsroot itself, preventingos.RemoveAll()from wiping an entire tree - Strict parameter validation — unknown params rejected, types enforced (
core/param_validator.go) - Temp files and backup IDs use
crypto/rand(not timestamps) - Backup IDs are sanitized to
[a-zA-Z0-9_-]to prevent path traversal - Temp files and backup metadata written with
0600permissions copyDirectory()skips symlinks- No
unsafepackage usage in production code
Dependencies
| Package | Version | Purpose |
|---|---|---|
github.com/mark3labs/mcp-go | v0.44.1 | MCP server SDK |
github.com/allegro/bigcache/v3 | v3.1.0 | File content cache |
github.com/patrickmn/go-cache | v2.1.0 | Directory and metadata cache |
github.com/panjf2000/ants/v2 | v2.11.5 | Goroutine pool |
github.com/fsnotify/fsnotify | v1.9.0 | File system event watching |
Documentation
Full documentation at filesystem.scopweb.com.
Changelog
See CHANGELOG.md for the full version history.
Current release: v4.2.1 — allowed-path root protection, main.go split, dry_run fix.
License
MIT