Filesystem MCP Server (@shtse8/filesystem-mcp)

What is @shtse8/filesystem-mcp?

@Shtse8/filesystem-mcp is a Node.js server implementing the Model Context Protocol (MCP) that provides AI agents with secure, token‑optimized filesystem operations. It confines all file access to the project root, supports batch processing of multiple files per request, and uses Zod validation. It is designed for developers using AI coding assistants like Claude or Cline.

How to use @shtse8/filesystem-mcp?

Configure the server in your MCP host (e.g., Cline, VSCode) using npx or bunx with the command @shtse8/filesystem-mcp. Alternatively, run the official Docker image, mounting your project directory to /app. The server uses its current working directory as the project root; ensure your host sets cwd appropriately.

Key features of @shtse8/filesystem-mcp

• Batch operations – read, write, edit multiple files in one request
• Token‑optimized – reduces round trips and overhead (50‑70% less token usage)
• Project root confinement – prevents path traversal outside the working directory
• Zod validation – all tool arguments validated for safety
• Detailed per‑item error reporting for batch operations
• 11+ tools including read, write, edit, search, move, copy, delete, chmod, chown

Use cases of @shtse8/filesystem-mcp

• AI agents reading, editing, and searching project files during development
• Batch refactoring across multiple files in a codebase
• Safe automated file generation, project setup, and directory management
• Integration with code assistants (Claude, Cline) for direct filesystem access

FAQ from @shtse8/filesystem-mcp

How does it differ from using shell commands?

It replaces individual shell commands (one file per operation, high token cost and latency) with direct API calls that batch 10+ files per request. This reduces token usage by 50–70% and latency 5–10×, with per‑item success/failure reporting instead of stderr parsing.

What security measures are in place?

All operations are confined to the server’s current working directory (project root). Path traversal is prevented. Built‑in chmod and chown tools allow permission control. Arguments are validated with Zod schemas.

Which tools support batch operations?

Most tools support batch processing: read_content, write_content, edit_file, search_files, replace_content, stat_items, create_directories, delete_items, move_items, copy_items, chmod_items, chown_items. Only list_files operates on a single path.

What runtime is required?

Node.js or Bun. The server is distributed as an npm package (@sylphx/filesystem-mcp) and a Docker image (sylphx/filesystem-mcp). It is built with TypeScript and uses pnpm for development.

How do I install and configure it?

Use npx @shtse8/filesystem-mcp or bunx @shtse8/filesystem-mcp in your MCP host’s mcpServers config. Alternatively, run docker run -i --rm -v /path/to/project:/app sylphx/filesystem-mcp:latest. Ensure the server’s cwd points to your project root.