Filesystem

Filesystem MCP lets AI agents perform secure, batch filesystem operations inside your project root. It provides a token-efficient, direct API to read, write, edit, search, and manage files and directories without shell overhead, while strictly confining all actions to the project root for safety.

How to use

You connect an MCP client to the Filesystem MCP server and issue batch operations that target multiple files or directories in a single request. Use the available tools to read, write, edit, search, replace content, list directories, and manage permissions. Each operation can handle multiple items, and you receive per-item results so you can see exactly what succeeded or failed.

How to install

Prerequisites: ensure you have Node.js installed on your system. A modern package manager (npm or pnpm) is required for building or installing the MCP client configurations.

Step-by-step setup options shown below. Choose the method that best fits your environment and workflow.

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

This configuration runs the MCP server via npx, using the latest package version. The server uses its own current working directory as the project root. Ensure your MCP host launches the command with cwd set to your project root.

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

This option uses bunx to run the MCP server, again with the project root as the working directory.

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

If you prefer containerized execution, use the official Docker image. Replace /path/to/your/project with your actual project path.

{
  "mcpServers": {
    "filesystem_mcp_local": {
      "command": "node",
      "args": ["/path/to/filesystem-mcp/dist/index.js"],
      "name": "Filesystem (Local Build)"
    }
  }
}

For a local build flow, run the build and then start the server using the node runtime on the built file. This provides a self-contained local MCP server.

Additional content

Security: the server confines all filesystem operations to the project root, preventing path traversal outside the cwd. It includes built-in permission controls and per-item status reporting for batch operations.

Performance: batch processing reduces token usage and round trips by handling multiple items in a single request. This enables faster responses and lower AI-server communication overhead.

Developer experience: easy setup with npx or Docker, a comprehensive set of filesystem tools, and full MCP standard compliance. The system validates arguments with strong schemas and provides detailed per-item results.

Troubleshooting tips: ensure your MCP host launches the server with the correct cwd (your project root). If you see permission errors, verify the target paths are within the project directory and that you have the necessary read/write permissions.

Available tools

read_content

Read file contents. Can process multiple files in a single request and return per-item results.

write_content

Write or append to files. Supports batch writes across multiple items.

edit_file

Perform surgical edits with diff output across multiple files.

search_files

Regex search across files with contextual results.

replace_content

Multi-file search and replace across the specified paths.

list_files

Recursively list files and directories.

stat_items

Get detailed status information for files and directories (permissions, size, mod time, etc.).

create_directories

Create directories along with necessary parent folders.

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 on multiple items.