Files MCP Server

Stdio MCP server for sandboxed file access — read files, search content, safely edit with checksums, and manage file structure.

Author: overment

Release status (2026-07-27): this repository intentionally pins @modelcontextprotocol/server and the test-only @modelcontextprotocol/client to 2.0.0-beta.5. These packages implement the 2026-07-28 release candidate, not a final published protocol. Re-run the final release gate before claiming final conformance.

The server uses the public serveStdio entry with legacy mode set to serve. The SDK chooses the protocol era from the opening exchange and pins one server instance to that stdio connection. Standard output is reserved for MCP frames; diagnostics are written only to standard error.

Warning

This server provides filesystem access to an AI agent. While it's sandboxed to specific directories, always:

Review tool outputs before confirming changes
Use dryRun=true to preview destructive operations
Keep backups of important files
Set FS_ROOTS to only the directories you want the agent to access

Motivation

Traditional file operations require precise paths and exact content — things LLMs struggle with. This server is designed so AI agents can:

Explore first — understand directory structure before acting
Find by name or content — locate files without knowing exact paths
Edit safely — checksum verification prevents stale overwrites
Preview changes — dry-run mode shows diffs before applying
Recover from errors — hints guide the agent to correct mistakes

The result: an agent that can reliably manage your Obsidian vault, documentation, notes, or any text-based file collection.

Features

✅ Directory Exploration — tree view with file counts, sizes, timestamps
✅ File Reading — line-numbered content with checksums for safe editing
✅ File & Content Search — filename search + literal/regex/fuzzy content search
✅ Safe Editing — checksum verification, dry-run preview, unified diffs
✅ Structural Operations — delete, rename, move, copy, mkdir, stat
✅ Multi-Mount Support — access multiple directories as virtual mount points
✅ Sandboxed — cannot access paths outside configured mounts

Design Principles

Explore before edit: Agent must read a file before modifying it (gets checksum + line numbers)
Preview before apply: dryRun=true shows exactly what would change
Clear feedback: Every response includes hints for next steps and error recovery
Compact by default: File details (size, modified) only shown when details=true
Single mount optimization: When one mount is configured, fs_read(".") shows contents directly

Quick Start

1. Install

cd files-mcp
bun install

2. Configure

Create .env:

# Directories the agent can access (comma-separated)
FS_ROOTS=/path/to/vault,/path/to/docs

# Or for a single directory:
# FS_ROOT=/path/to/vault

# Optional
LOG_LEVEL=info
MAX_FILE_SIZE=1048576

# Force-include ignored folders (comma-separated relative paths)
# These folders will be visible even if matched by .gitignore
# FS_INCLUDE=data,build/output

3. Run

bun dev

4. Connect to Client

Claude Desktop / Cursor:

{
  "mcpServers": {
    "filesystem": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/files-mcp/src/index.ts"],
      "env": {
        "FS_ROOTS": "/Users/you/vault,/Users/you/docs"
      }
    }
  }
}

MCP Bundle (MCPB)

This server is also available as an MCP Bundle (.mcpb) for one-click installation in supported apps like Claude Desktop, Alice, and other MCPB-compatible applications.

What is MCPB?

MCP Bundles are zip archives containing a local MCP server and a manifest.json that describes the server and its capabilities. The format enables end users to install local MCP servers with a single click — no manual configuration required.

Installing from MCPB

Download the files-mcp.mcpb file
Open it with a compatible app (Claude Desktop, Alice, etc.)
Configure the Root Directory when prompted — this is the directory the agent will have access to
Done! The server is installed and ready to use

manifest.json

The manifest defines:

Server configuration — command, args, environment variables
Tools — fs_read, fs_search, fs_write, fs_manage with descriptions
User config — prompts for FS_ROOT directory during installation

{
  "manifest_version": "0.2",
  "name": "files-mcp",
  "version": "1.0.0",
  "server": {
    "type": "node",
    "entry_point": "dist/index.js",
    "mcp_config": {
      "command": "node",
      "args": ["${__dirname}/dist/index.js"],
      "env": {
        "FS_ROOT": "${user_config.FS_ROOT}"
      }
    }
  },
  "user_config": {
    "FS_ROOT": {
      "type": "directory",
      "title": "Root Directory",
      "description": "The directory the agent will have access to.",
      "required": true
    }
  }
}

The ${user_config.FS_ROOT} syntax injects the user-selected directory into the server's environment at runtime.

Server Instructions (What the Model Sees)

🔒 SANDBOXED FILESYSTEM — This tool can ONLY access specific mounted directories.
   You CANNOT access arbitrary system paths like /Users or C:\.
   Always start with fs_read(".") to see available mounts.

⚠️ ALWAYS read a file BEFORE answering questions about its content.
⚠️ ALWAYS read a file BEFORE modifying it (you need the checksum).

MANDATORY WORKFLOW:
1. fs_read(".") → see available mounts
2. fs_search(...) → locate files or content
3. fs_read("path/file.md") → get content + checksum
4. fs_write with dryRun=true → preview diff
5. fs_write with dryRun=false + checksum → apply change
6. fs_manage for structural changes (delete/rename/move/copy/mkdir)

Tools

`fs_read`

Read files or list directories.

Input:

{
  path: string;                    // "." for root, "docs/", "notes/todo.md"
  
  // Options
  depth?: number;                  // Directory traversal depth (default 1)
  details?: boolean;               // Include size/modified (default false)
  lines?: string;                  // "10-50" for partial read
  types?: string[];                // Filter directory listing by type
  glob?: string;                   // Glob filter for listing
  exclude?: string[];              // Exclude patterns
  respectIgnore?: boolean;         // Honor .gitignore (default true)
}

Output:

{
  success: boolean;
  path: string;
  type: "directory" | "file";
  
  // For directories
  entries?: Array<{ path, kind, children?, size?, modified? }>;
  summary?: string;
  
  // For files
  content?: {
    text: string;        // With line numbers
    checksum: string;    // Pass to fs_write
    totalLines: number;
    range?: { start: number; end: number };
    truncated: boolean;
  };
  
  hint: string;          // Next action suggestion
}

`fs_search`

Find files by name and search content within files.

Input:

{
  path: string;                   // "." for all mounts
  query: string;                  // Search term
  target?: "all" | "filename" | "content";
  patternMode?: "literal" | "regex" | "fuzzy";
  caseInsensitive?: boolean;
  wholeWord?: boolean;
  multiline?: boolean;
  types?: string[];
  glob?: string;
  exclude?: string[];
  depth?: number;                 // Default 5
  maxResults?: number;            // Default 100, max 1000
  respectIgnore?: boolean;
}

Output:

{
  success: boolean;
  query: string;
  files: Array<{ name: string; path: string }>;        // Filename matches
  content?: Array<{ path: string; line: number; text: string }>;  // Content matches
  totalCount: number;
  truncated: boolean;          // True if maxResults cap was hit
  error?: { code: string; message: string };
  hint: string;                // Actionable guidance
}

`fs_write`

Create or update files with safety features.

Input:

{
  path: string;
  operation: "create" | "update";
  
  // For create
  content?: string;
  
  // For update — target by lines
  lines?: string;                  // "10-15" — PREFERRED
  
  // For update — action
  action?: "replace" | "insert_before" | "insert_after" | "delete_lines";
  content?: string;                // New content
  
  // Safety
  checksum?: string;               // From fs_read — RECOMMENDED
  dryRun?: boolean;                // Preview only (default false)
  createDirs?: boolean;            // Auto-create parent dirs (default true)
}

Output:

{
  status: "applied" | "preview" | "error";
  path: string;
  operation: "create" | "update";
  
  result?: {
    action: string;              // "created", "would_create", "replaced", etc.
    targetRange?: { start: number; end: number };  // For updates
    newChecksum?: string;        // After apply
    diff?: string;               // Unified diff
  };
  
  error?: {
    code: string;
    message: string;
    recoveryHint: string;        // Always present on errors
  };
  
  hint: string;                  // Actionable guidance
}

`fs_manage`

Structural filesystem operations.

Input:

{
  operation: "delete" | "rename" | "move" | "copy" | "mkdir" | "stat";
  path: string;
  target?: string;                 // rename/move/copy
  recursive?: boolean;             // mkdir/copy/move only (default false)
  force?: boolean;                 // overwrite (default false)
}

Note: Delete only works on single files or empty directories (no recursive delete for safety).


**Output:**
```ts
{
  success: boolean;
  operation: string;
  path: string;
  target?: string;
  stat?: { size, modified, created, isDirectory };
  hint: string;
}

Examples

1. Explore the vault

{ "path": "." }

Response:

18 items (15 files, 3 directories)

- Core/
- Projects/
- Books/
- map.md
- inbox.md
...

hint: "Showing contents of 'vault'. Use fs_read on any path to explore deeper."

2. Search for a file by name

{ "path": ".", "query": "todo", "target": "filename" }

Response:

Found 3 filename match(es)

- Core/Todo.md
- Projects/Todo.md
- inbox.md
...

hint: "Found 3 filename match(es)."

3. Read a file

{ "path": "Core/Values.md" }

Response:

File read complete. Checksum: a1b2c3d4e5f6.

   1| # Values
   2|
   3| ## Integrity
   4| Be honest, even when it's hard.
   5|
   6| ## Growth
   7| Learn something new every day.
...

hint: "To edit this file, use fs_write with checksum a1b2c3d4e5f6."

4. Find all incomplete tasks

{ "path": ".", "query": "- \\[ \\] ", "patternMode": "regex", "target": "content" }

Response:

Found 7 content match(es) in 4 file(s).

- Projects/Alice.md:12 — "- [ ] Implement search"
- Projects/Alice.md:15 — "- [ ] Add tests"
- inbox.md:3 — "- [ ] Review PR"
...

5. Replace text (preview first, line-based)

{
  "path": "Core/Values.md",
  "operation": "update",
  "action": "replace",
  "lines": "3",
  "content": "Act with integrity",
  "checksum": "a1b2c3d4e5f6",
  "dryRun": true
}

Response:

DRY RUN — no changes applied.

--- a/Core/Values.md
+++ b/Core/Values.md
@@ -3,1 +3,1 @@
-Be honest, even when it's hard.
+Act with integrity, even when it's hard.

hint: "Review the diff above. Run with dryRun=false to apply."

6. Move a file to archive

{
  "operation": "move",
  "path": "Projects/Alice.md",
  "target": "Archive/Alice.md",
  "force": true
}

Response:

Move completed successfully.

7. Mark task as complete

{
  "path": "inbox.md",
  "operation": "update",
  "action": "replace",
  "lines": "3",
  "content": "- [x] Review PR",
  "checksum": "xyz789"
}

Response:

replaced 1 line(s). New checksum: abc123.

hint: "The diff above shows what changed."

Configuration

Variable	Default	Description
`FS_ROOTS`	`.`	Comma-separated paths the agent can access
`FS_ROOT`	`.`	Single path (backward compatibility)
`MCP_NAME`	`files-mcp`	Server name
`MCP_VERSION`	`1.0.0`	Server version
`LOG_LEVEL`	`info`	Log level: debug, info, warning, error
`MAX_FILE_SIZE`	`1048576`	Max file size in bytes (1MB)
`FS_INCLUDE`	(none)	Comma-separated relative paths to force-include even if gitignored (recursive)

Force-Include Ignored Folders

Some folders may be in .gitignore but still need to be searchable by the agent (e.g., generated data, build output). Use FS_INCLUDE to whitelist them:

FS_INCLUDE=docs,workspaces,data/embeddings

Paths are relative to the mount root and recursive — data includes data/, data/sub/, data/sub/deep/, etc. This overrides .gitignore, .ignore, and all default ignore patterns.

Multi-Mount Setup

Access multiple directories:

FS_ROOTS=/Users/me/vault,/Users/me/projects,/Users/me/notes

Each path becomes a mount named after its folder:

vault/ → /Users/me/vault
projects/ → /Users/me/projects
notes/ → /Users/me/notes

Client Configuration

Claude Desktop:

{
  "mcpServers": {
    "filesystem": {
      "command": "bun",
      "args": ["run", "/path/to/files-mcp/src/index.ts"],
      "env": {
        "FS_ROOTS": "/Users/me/vault"
      }
    }
  }
}

Cursor:

{
  "filesystem": {
    "command": "bun",
    "args": ["run", "/path/to/files-mcp/src/index.ts"],
    "env": {
      "FS_ROOTS": "/Users/me/vault"
    }
  }
}

Development

bun dev           # Start with hot reload
bun test          # Run tests
bun run typecheck # TypeScript check
bun run lint      # Lint code
bun run test:protocol       # Official-client source protocol matrix
bun run build               # Production build
bun run test:protocol:built # Repeat handshake against the Node artifact
bun run format:check        # Check formatting
bun run inspector           # Test with MCP Inspector

Architecture

src/
├── index.ts              # Entry point: stdio transport
├── config/
│   ├── env.ts            # Environment config & mount parsing
│   └── metadata.ts       # Tool descriptions
├── core/
│   ├── capabilities.ts   # Server capabilities
│   └── mcp.ts            # McpServer builder
├── tools/
│   ├── index.ts          # Tool registration
│   ├── fs-read.tool.ts   # Read and explore
│   ├── fs-search.tool.ts # Filename + content search
│   ├── fs-write.tool.ts  # Create and update
│   └── fs-manage.tool.ts # Structural operations
├── lib/
│   ├── checksum.ts       # SHA256 checksums
│   ├── diff.ts           # Unified diff generation
│   ├── filetypes.ts      # Text/binary detection
│   ├── ignore.ts         # .gitignore support
│   ├── lines.ts          # Line manipulation
│   ├── paths.ts          # Multi-mount path resolution
│   └── patterns.ts       # Pattern matching utilities
└── utils/
    ├── errors.ts         # Error utilities
    └── logger.ts         # Logging

Troubleshooting

Issue	Solution
"SANDBOXED FILESYSTEM: Absolute paths not allowed"	Use relative paths within mounts. Start with `fs_read(".")` to see available mounts.
"Path does not match any mount"	Check `FS_ROOTS` is set correctly. Paths must start with a mount name (e.g., `vault/notes.md`).
"CHECKSUM_MISMATCH"	File changed since you read it. Re-read with `fs_read` to get fresh content.
"DIRECTORY_NOT_EMPTY"	Delete only works on empty directories. For move/copy, use `recursive=true`.
"ALREADY_EXISTS"	Target already exists. Use `force=true` where supported.
Binary file errors	Only text files can be read/written. Check file extension.
Single mount still shows "docs"	Restart the MCP server after changing `FS_ROOTS`.

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
mcpb		mcpb
src		src
tests		tests
.gitignore		.gitignore
README.md		README.md
biome.json		biome.json
env.example		env.example
manifest.json		manifest.json
overview.html		overview.html
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Files MCP Server

Motivation

Features

Design Principles

Quick Start

1. Install

2. Configure

3. Run

4. Connect to Client

MCP Bundle (MCPB)

What is MCPB?

Installing from MCPB

manifest.json

Server Instructions (What the Model Sees)

Tools

fs_read

fs_search

fs_write

fs_manage

Examples

1. Explore the vault

2. Search for a file by name

3. Read a file

4. Find all incomplete tasks

5. Replace text (preview first, line-based)

6. Move a file to archive

7. Mark task as complete

Configuration

Force-Include Ignored Folders

Multi-Mount Setup

Client Configuration

Development

Architecture

Troubleshooting

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`fs_read`

`fs_search`

`fs_write`

`fs_manage`