filesystem

This MCP server exposes a secure filesystem toolkit that AI agents can call through the MCP protocol. It consolidates 11+ filesystem operations (such as read_content, write_content, edit_file, search_files, replace_content, list_files, stat_items, create_directories, delete_items, move_items, copy_items, chmod_items, chown_items) into a batched API, allowing multiple paths per request and returning per-item status. Operations are confined to the project root launched at startup, enabling safe read/write, permission changes, and directory traversals without shell spawns. To use it, configure the server in your MCP host (for example via npx or docker as shown in the installation section), then send an MCP request specifying the server_name filesystem-mcp and the tool_name you want to execute along with an arguments payload. The tooling emphasizes token efficiency by batching many targets in a single request and returns detailed per-item results for robust error handling and auditing.

Prerequisites:

• Node.js (recommended latest LTS) or a compatible MCP host that can run Node-based servers
• Access to npm or bunx (optional, for alternative installation)

Method 1: npx/bunx (Recommended)

Using npx:

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

Using bunx:

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

Important: The server uses its own Current Working Directory (cwd) as the project root. Ensure your MCP host launches the command with cwd set to your project's root directory.

Method 2: Docker

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

Remember to replace /path/to/your/project with your actual project path.

Method 3: Local Build (Development)

# Clone repository
git clone https://github.com/SylphxAI/filesystem-mcp.git
cd filesystem-mcp

# Install dependencies
pnpm install

# Build
pnpm run build

# Watch mode (auto-rebuild)
pnpm run dev

MCP Host Configuration example (local build):

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

Tips and notes:

• The toolkit enforces project-root confinement and path traversal protections by design; ensure your MCP host starts with the correct cwd to reflect your project root.
• Many tools support batch operations, returning per-item statuses to aid debugging and auditing.
• If you run with Docker, volume-mount your project directory so the server operates on real files within the project scope.
• When using batched operations, you can significantly lower token usage and latency due to reduced round-trips compared to issuing individual file operations.
• The npm package name is @sylphlab/filesystem-mcp; check for updates on npm to stay current with tooling improvements.
• If you encounter permission issues on POSIX systems, verify that the MCP host process has the necessary rights or use chmod/chown tools provided by the suite.