Filesystem

Filesystem MCP Server provides token-optimized, batch-capable filesystem operations for AI agents. It confines all actions to your project root, offers per-item results, and exposes a direct API to read, write, edit, search, and manage files and directories without spawning shell commands.

How to use

You connect your MCP client to the Filesystem MCP Server and send requests to operate on files and directories. Take advantage of batch operations to process multiple items in a single request, which reduces token usage and latency. Every operation runs within the project root you start the server from, and you receive detailed per-item results so you can identify successes and failures precisely.

Typical usage scenarios include reading contents of several files in one call, writing updates to multiple files at once, editing several files with surgical changes, listing directory trees, and managing files and permissions in a safe, confined environment.

How to install

Choose the installation method that fits your environment. You can run the server directly via npx, use bunx for a lighter startup, deploy with Docker, or run a local build for development.

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (npx)"
    }
  }
}

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "bunx",
      "args": ["@sylphlab/filesystem-mcp"],
      "name": "Filesystem (bunx)"
    }
  }
}

Docker provides a containerized option. Run the container and mount your project directory as the working directory inside the container.

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/your/project:/app",
        "sylphlab/filesystem-mcp:latest"
      ],
      "name": "Filesystem (Docker)"
    }
  }
}

Additional setup and notes

If you’re running locally for development, you can build the TypeScript sources and run a local start. Your MCP host should set the working directory (cwd) to your project root when launching the command.

Security and safety

All operations are confined to the project root established at launch. The server includes path traversal safeguards and built-in permission controls to prevent unauthorized access or modification outside of the intended workspace.

Examples and tips

Use batch operations to read, write, or modify several files in a single call. Leverage per-item status reporting to quickly identify which items succeeded or failed and why.

Available tools

read_content

Read file contents for one or multiple paths with per-item results.

write_content

Write or append content to files with per-item results.

edit_file

Apply surgical edits with diff-like output for multiple files.

search_files

Search files with regular expressions and provide contextual results.

replace_content

Perform multi-file find-and-replace operations.

list_files

List files and directories recursively starting from a given path.

stat_items

Get detailed status information for multiple items.

create_directories

Create directories with parent paths as needed.

delete_items

Remove files or directories in batch.

move_items

Move or rename files and directories in batch.

copy_items

Copy files and directories in batch.

chmod_items

Change POSIX permissions on multiple items.

chown_items

Change ownership for multiple items.