Files MCP Server

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

Author: overment

[!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

1. Download the files-mcp.mcpb file
2. Open it with a compatible app (Claude Desktop, Alice, etc.)
3. Configure the Root Directory when prompted — this is the directory the agent will have access to
4. 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_R

... View full README on GitHub