Filesystem MCP

Your agent touched the repo. Did it stay in the project?

Secure, token-optimized filesystem operations for AI agents — batch reads, surgical edits, and project-root confinement without shell spawn overhead.

npm version Docker Pulls License TypeScript

Batch operations · Project root safety · Zod validation · 13 MCP tools · Docker-ready

⭐ Star this repo if agents should read and edit your codebase safely — not spawn shells per file. · Quick start · See it work · Why not shell commands? · Roadmap

The problem

Agents need filesystem access to read code, apply edits, and search across a repo. The default path is shell commands — one spawn per operation, no batching, stderr parsing, and paths that can wander outside the project.

That costs tokens, adds latency, and turns every file touch into a trust exercise.

Filesystem MCP is built for the moment your agent needs fast, bounded, batch-friendly file operations — confined to the project root.

Why not shell commands?

Shell commands per file Filesystem MCP
One operation per spawn Batch 10+ files in one MCP call
Full shell access Confined to server cwd at launch
stderr parsing Per-item success/failure in structured JSON
High token round trips Fewer host↔server calls
Path traversal risk Relative paths only; traversal blocked
No schema Zod-validated arguments on every tool

Full benchmark contract: docs/benchmark.md.

See it work

Configure once. Read many files in one call.

claude mcp add filesystem -- npx @sylphx/filesystem-mcp

{
  "paths": ["src/index.ts", "package.json", "README.md"]
}

read_content returns per-file results in one response:

{
  "results": [
    { "path": "src/index.ts", "content": "...", "success": true },
    { "path": "package.json", "content": "...", "success": true },
    { "path": "README.md", "content": "...", "success": true }
  ]
}

Important: launch the MCP server with cwd set to your project root. All paths are relative to that directory.

Why agents use it

Need What you get
Read multiple files read_content — batch paths, optional line ranges
Write or append write_content — multiple files per call
Surgical edits apply_diff, replace_content — diff output and per-file status
Search the tree search_files — regex with context
Refactor across files replace_content — multi-file search & replace
Explore structure list_files — recursive listing with optional stats
Move/copy/delete move_items, copy_items, delete_items
Permissions chmod_items, chown_items
Inspect metadata stat_items, create_directories

Quick Start

Claude Code

claude mcp add filesystem -- npx @sylphx/filesystem-mcp

Run from your project directory so cwd is the repo root.

Claude Desktop / any MCP host

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["@sylphx/filesystem-mcp"]
    }
  }
}

Set the host's working directory to your project root.

Docker

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/your/project:/app",
        "sylphx/filesystem-mcp:latest"
      ]
    }
  }
}

Local development

git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp
bun install
bun run build
bun run test

MCP Tool Surface

Tool Use it when the agent needs to...
read_content Read one or more files (optional line ranges)
write_content Write or append to files
apply_diff Apply structured diffs across files
search_files Regex search with context lines
replace_content Multi-file search and replace
list_files List a directory tree (optional stats)
stat_items Get detailed file/directory metadata
create_directories Create directories (with parents)
delete_items Remove files or directories
move_items Move or rename items
copy_items Copy files or directories
chmod_items Change POSIX permissions
chown_items Change ownership

Release proof

Claims are backed by CI benchmark:release-gate, safety fixture corpus, and the shipped-path matrix (Rust-default primary tools).

bun run benchmark:release-gate

Artifact: benchmark-artifacts/filesystem_release_gate.json — must report status: passed before release.

Performance benchmarks

Reproduce local throughput on the shipped Rust CLI path:

bunx vitest bench __tests__/benchmarks/throughput.bench.ts --run

See docs/benchmark.md for scenarios, design goals, and how to interpret results.

Security model

  • All operations confined to the server cwd at launch.
  • Absolute paths rejected; path traversal blocked.
  • Zod schemas validate every tool argument.
  • Batch tools return per-item status — one failure does not hide the rest.

Documentation

Topic Link
Docs site sylphxai.github.io/filesystem-mcp
Introduction docs/guide/introduction.md
Benchmarks docs/benchmark.md

Development

bun run validate    # lint + typecheck + test
bun run docs:build  # VitePress + API docs
bun run benchmark   # vitest bench

Support

Help this reach more builders

If shell-per-file agent workflows have burned your tokens or your trust in path safety, this project is for you.

⭐ Star the repo — it helps more agent builders find secure, batch-friendly filesystem access.

Discovery (in progress)

Channel Status
Glama MCP directory Listed — claim server for full discoverability
Official MCP Registry Not listed yet
mcp.so submit Not listed yet — directory submission
mcpservers.org submit Not listed yet — free web-form submission

Know another MCP directory? Open an issue with the link.

License

MIT © Sylphx