files-stdio

Files MCP Server provides a sandboxed, stdio-based interface for safe, AI-assisted filesystem access. It exposes a small, well-defined set of tools that let an agent explore mounts, read files with line numbers and checksums, search by filename or content, and perform safe edits or structural changes. The design emphasizes exploration before modification, previewing changes with dry-run, and returning actionable hints to guide the agent through each step. The server supports multiple mounts as virtual roots so the agent can inspect and operate within a controlled subset of the filesystem.

Prerequisites:

• Install a Node.js-compatible runtime with Bun available (the server example uses Bun for dev/start).
• Ensure FS_ROOTS or FS_ROOT are configured to point to directories the agent may access.
• Have a supported MCP client or environment ready to connect to the MCP server.

Installation steps:

1. Install dependencies (example uses Bun):

cd files-mcp
bun install

2. Configure access roots (example shown in .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 the server in development mode (example uses Bun):

bun dev

4. If using an MCP client, connect by providing the mcp configuration (example snippet below):

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

Tips and caveats:

• Always start with fs_read(".") to list available mounts before performing reads or edits.
• Use fs_search to locate files by name or by content with literal/regex/fuzzy matching.
• When editing, prefer dryRun=true to preview diffs before applying changes and always supply the checksum obtained from a preceding fs_read call.
• For multiple mounts, remember that structural operations (delete/rename/move/copy/mkdir) apply within the configured mounts only.
• If you encounter permission or path issues, verify FS_ROOTS/FS_ROOT values and ensure the agent is allowed to access the intended directories.
• When using MCP Bundles, the manifest describes the server and provides prompts for FS_ROOT during installation; use it to guide initial root configuration.