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 form

... View full README on GitHub