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.

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.

Related MCP server: image-reader MCP Server

Why not shell commands?

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

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

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

Development

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

Support

• Issues

• Discussions

• npm package

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)

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

License

MIT © Sylphx