Filesystem MCP — Use Cases, Install & Live Demo

Why use it

Key features

Hard path sandboxing — roots configured at launch, no escape via symlink or ..
Read, write, edit-by-line, recursive content search, directory tree
Binary-aware — reads images, PDFs, audio as base64 blobs
Zero setup — npx -y @modelcontextprotocol/server-filesystem <dir> and go
Published and signed by the MCP reference team

Live Demo

What it looks like in practice

filesystem.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "filesystem",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/workspace"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "filesystem": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@modelcontextprotocol/server-filesystem",
          "/workspace"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /workspace

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use Filesystem

How to refactor a function across an entire codebase without breaking it

👤 Engineers renaming/reshaping an API that's used in many files ⏱ ~20 min intermediate

When to use: You need to rename a function, change its signature, or inline a helper — and it's used in 30+ files across the repo.

Prerequisites

Clean git working tree — git status shows nothing staged — so you can git diff to review and git restore if needed
Filesystem root scoped to the repo — Launch with npx -y @modelcontextprotocol/server-filesystem /abs/path/to/repo

Flow

Find every callsite

Search the codebase for every usage of getUserProfile(. Group matches by file and give me a count per file.✓ Copied

→ File list with match counts, excluding tests vs source distinction
Dry-run the edit on one file

Show me what the edit would look like in src/api/users.ts — a diff, not the full file. Don't write yet.✓ Copied

→ Minimal diff patch, not a full-file rewrite
Apply to all files and report

Apply the same transformation to every file from step 1. Use edit_file (line-level), not write_file (overwrite). Tell me any file where the pattern didn't match cleanly.✓ Copied

→ Per-file success/skip log

Outcome: A focused, reviewable git diff you can run tests against — no surprise whole-file rewrites.

Pitfalls

Claude uses write_file and silently drops half the file when the edit is complex — Explicitly require edit_file for in-place changes; only allow write_file for files being created fresh
Match hits unrelated code (e.g. getUserProfileAvatar) — Anchor the search: getUserProfile( with the trailing paren, or use a word-boundary regex

Combine with: git · github

Triage a crash by reading production log files locally

👤 On-call engineers with logs on disk ⏱ ~15 min beginner

When to use: You've downloaded a log bundle from a customer incident and need to find the needle without grep-fu.

Prerequisites

Logs on disk — Download/unzip under a dedicated /incidents/<ticket>/ folder

Flow

Get a structural overview

List files under /incidents/TICKET-1234/. For each log file, show size and the first + last timestamp inside.✓ Copied

→ Time-bounded inventory
Find the error cluster

Search all .log files for the pattern ERROR|FATAL|panic. Give me the 10 minutes with the highest density of hits.✓ Copied

→ Time window narrowed to minutes, not hours
Read context around the first fatal

Read 50 lines of context around the first FATAL line in app.log. Explain what the system was doing right before it crashed.✓ Copied

→ Narrative reconstruction, not log regurgitation

Outcome: A 5-sentence timeline you can paste into the incident doc.

Pitfalls

Large log files (>50MB) blow the model context — Ask for head/tail + grep-style extraction only; never ask Claude to 'read the whole file' on anything big

Combine with: sentry · github

Ask questions about a folder of PDFs, Markdown, and docs

👤 Researchers, analysts with a pile of reference material ⏱ ~15 min beginner

When to use: You have 50 papers/contracts/reports in a folder and need to extract one specific fact or compare across them.

Prerequisites

Documents organized in one folder — Flatten to one directory or a shallow tree; Claude traverses better on flatter structures

Flow

Index the folder

List every file under /research/2026-market-study/. For each, tell me the filename and the first 200 characters.✓ Copied

→ Inventory with quick previews
Ask the real question

Which of these documents mentions 'contractual indemnity cap'? For each hit, quote the exact sentence and give me the filename.✓ Copied

→ Citations with filename, not just vibes
Cross-document synthesis

Compare the indemnity caps across the 3 docs that have them. Which is most favorable to us and why?✓ Copied

→ Side-by-side comparison with direct quotes

Outcome: Answers with filename+quote citations you can verify in 30 seconds.

Pitfalls

Scanned PDFs are image-based — search-by-content fails — Run OCR first (e.g. ocrmypdf) or use a dedicated PDF MCP; note 'unsearchable' files before starting
Claude summarizes and loses source attribution — Always require filename + exact quote in the prompt; reject answers without it

Combine with: memory

Scaffold a new project from a spec in one chat turn

👤 Engineers starting a new service/lib/prototype ⏱ ~10 min beginner

When to use: You have a one-paragraph spec and want the boilerplate (folders, package.json, README, tests) materialized without copying from a template repo.

Prerequisites

Empty target directory — mkdir /projects/newthing and point the filesystem root at its parent

Flow

Agree on layout before writing

I want a TypeScript Node CLI tool that does X. Propose the folder structure and list every file you'd create with a one-line purpose. Don't write yet.✓ Copied

→ File-by-file plan — you can veto before disk is touched
Write the files

Looks good. Create all those files under /projects/newthing/. Use minimal, idiomatic content — no placeholder comments, no 'TODO' stubs.✓ Copied

→ Files on disk, compiles/lints clean first try
Verify by reading back

Read every file you just created and confirm the project would pass tsc --noEmit and npm test. Fix anything that wouldn't.✓ Copied

→ Self-check with concrete fixes, not hand-waving

Outcome: A working skeleton project in 3 minutes instead of 30.

Pitfalls

Claude writes files and then forgets what it wrote mid-session — Have it produce the file plan first, then write; re-reading at the end catches drift

Combine with: git · github

Combinations

Pair with other MCPs for X10 leverage

filesystem + github

Edit files locally, push a branch and open a PR without leaving the chat

Fix the typo in src/utils/format.ts:42, then push a new branch fix/typo-format and open a PR titled 'fix: typo in format.ts'.✓ Copied

filesystem + git

Make edits, review the diff, commit — all inside Claude

Refactor the 3 duplicate helpers in src/ into one shared util. Show me the diff before committing, then commit with a clean message.✓ Copied

filesystem + sqlite

Read a CSV from disk and load it into a SQLite table for analysis

Read /data/orders.csv, infer types, and load it into /data/analysis.db as table orders.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
read_text_file	path: str, head?: int, tail?: int	Read a text file; use head/tail to avoid loading huge files	free
read_media_file	path: str	Read images, PDFs, audio as base64 for multimodal input	free
read_multiple_files	paths: str[]	Batch-read related files in one turn (faster than N calls)	free
write_file	path: str, content: str	Create a new file or fully replace one — destructive	free
edit_file	path: str, edits: [{oldText, newText}], dryRun?: bool	Safer line-level edits; always prefer over write_file for existing files	free
create_directory	path: str	Make a directory (recursive, mkdir -p style)	free
list_directory	path: str	Non-recursive ls	free
directory_tree	path: str	Overview of a project structure at a glance	free
move_file	source: str, destination: str	Rename or relocate	free
search_files	path: str, pattern: str, excludePatterns?: str[]	Recursive content search — like grep	free
get_file_info	path: str	Stat a file without reading contents	free
list_allowed_directories	none	Confirm which roots the server was launched with	free

Cost & Limits

What this costs to run

API quota: Unlimited — it's local I/O
Tokens per call: Depends on file size — budget ~1 token per 4 chars of file content
Monetary: Free
Tip: Use search_files and head/tail rather than reading whole files. A 2MB log dumped into context costs ~500k tokens.

Security

Permissions, secrets, blast radius

Minimum scopes: filesystem-read filesystem-write (if mutating)

Credential storage: No credentials — access is via the root directories passed as args

Data egress: None from the server — file contents ship to your LLM provider via the MCP client as context

Never grant: root=/ root=$HOME root=/etc or /var

Never point the root at / or $HOME — scope to the one project directory you're working in.
Claude will overwrite without asking. Commit to git before any multi-file edit session.

Troubleshooting

Common errors and fixes

Error: Path is not within allowed directories

The file is outside every root passed at launch. Relaunch the server with an additional root arg, or use list_allowed_directories to see what's actually allowed.

Verify: Ask Claude to call `list_allowed_directories`

ENOENT: no such file or directory

Path typo or wrong working directory assumption. Use directory_tree on the root to see the real layout.

edit_file: oldText not found

The oldText pattern must match exactly including whitespace. Ask Claude to read_text_file first and copy the exact substring.

Huge file freezes the client

Don't read full files larger than a few MB. Use head/tail params on read_text_file, or search_files to find just the relevant lines.

Verify: Check file size with `get_file_info` first

Alternatives

Filesystem vs others

Alternative	When to use it instead	Tradeoff
git MCP	You need version-aware operations (diff, blame, log) rather than raw file I/O	No write tools; read-only through a git lens
GitHub MCP	Files live in a remote repo and you don't want a local clone	Requires a PAT; per-file latency is much higher than local disk
JetBrains MCP	You want edits to show up in your running IDE instance with refactor tooling	Requires a JetBrains IDE open; heavier than the plain filesystem

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills