Filesystem MCP — ARCHIVED

ARCHIVED / NON-PRIMARY
This product is not an active Sylphx agent-instrument.
Prefer independent products: Citra, Iris, Cue, Prism, Spine, Lookout.

Historical source remains for reference only. Do not treat npm/Docker badges or install CTAs below as current install authority.

Historical README (archived product)

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.

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.

filesystem-mcp

Links

README