filesystem-mcp

<div align="center"> # Filesystem MCP 📁 **Secure filesystem operations for AI agents - Token-optimized with batch processing** [](https://www.npmjs.com/package/@sylphlab/filesystem-mcp) [](https://hub.docker.com/r/sylphlab/filesystem-mcp) [](https://github.com/SylphxAI/filesystem-mcp/blob/main/LICENSE) **Batch operations** • **Project root safety** • **Token optimized** • **Zod validation** [Quick Start](#-quick-start) • [Installation](#-installation) • [Tools](#-features) <a href="https://glama.ai/mcp/servers/@sylphlab/filesystem-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@sylphlab/filesystem-mcp/badge" alt="Filesystem MCP Server" /> </a> </div> --- ## 🚀 Overview Empower your AI agents (like Claude/Cline) with secure, efficient, and token-saving access to your project files. This Node.js server implements the [Model Context Protocol (MCP)](https://docs.modelcontextprotocol.com/) to provide a robust set of filesystem tools. **The Problem:** ``` Traditional AI filesystem access: - Shell commands for each operation ❌ - No batch processing (high token cost) ❌ - Unsafe (no project root boundaries) ❌ - High latency (shell spawn overhead) ❌ ``` **The Solution:** ``` Filesystem MCP Server: - Batch operations (10+ files at once) ✅ - Token optimized (reduce round trips) ✅ - Secure (confined to project root) ✅ - Direct API (no shell overhead) ✅ ``` **Result: Safe, fast, and token-efficient filesystem operations for AI agents.** --- ## ⚡ Performance Advantages ### Token & Latency Optimization | Metric | Individual Shell Commands | Filesystem MCP | Improvement | |--------|---------------------------|----------------|-------------| | **Operations/Request** | 1 file | 10+ files | **10x reduction** | | **Round Trips** | N operations | 1 request | **N× fewer** | | **Latency** | Shell spawn per op | Direct API | **5-10× faster** | | **Token Usage** | High overhead | Batched context | **50-70% less** | | **Error Reporting** | stderr parsing | Per-item status | Detailed | ### Real-World Benefits - **Batch file reads** - Read 10 files in one request vs 10 requests - **Multi-file edits** - Edit multiple files with single tool call - **Recursive operations** - List entire directory trees efficiently - **Detailed status** - Per-item success/failure reporting --- ## 🎯 Why Choose This Server? ### Security & Safety - **🛡️ Project Root Confinement** - All operations restricted to `cwd` at launch - **🔒 Permission Control** - Built-in chmod/chown tools - **✅ Validation** - Zod schemas validate all arguments - **🚫 Path Traversal Prevention** - Cannot escape project directory ### Efficiency & Performance - **⚡ Batch Processing** - Process multiple files/directories per request - **🎯 Token Optimized** - Reduce AI-server communication overhead - **🚀 Direct API** - No shell process spawning - **📊 Detailed Results** - Per-item status for batch operations ### Developer Experience - **🔧 Easy Setup** - `npx`/`bunx` for instant use - **🐳 Docker Ready** - Official Docker image available - **📦 Comprehensive Tools** - 11+ filesystem operations - **🔄 MCP Standard** - Full protocol compliance --- ## 📦 Installation ### Method 1: npx/bunx (Recommended) The simplest way - always uses latest version from npm. **Using npx:** ```json { "mcpServers": { "filesystem-mcp": { "command": "npx", "args": ["@sylphlab/filesystem-mcp"], "name": "Filesystem (npx)" } } } ``` **Using bunx:** ```json { "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 (e.g., Cline/VSCode) launches the command with `cwd` set to your project's root directory. ### Method 2: Docker Use the official Docker image for containerized environments. ```json { "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) ```bash # 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:** ```json { "mcpServers": { "filesystem-mcp": { "command": "node", "args": ["/path/to/filesystem-mcp/dist/index.js"], "name": "Filesystem (Local Build)" } } } ``` --- ## 🚀 Quick Start Once configured in your MCP host (see Installation), your AI agent can immediately use the filesystem tools. ### Example Agent Interaction ```xml <use_mcp_tool> <server_name>filesystem-mcp</server_name> <tool_name>read_content</tool_name> <arguments>{"paths": ["src/index.ts", "package.json"]}</arguments> </use_mcp_tool> ``` **Server Response:** ```json { "results": [ { "path": "src/index.ts", "content": "...", "success": true }, { "path": "package.json", "content": "...", "success": true } ] } ``` --- ## 📋 Features ### File Operations | Tool | Description | Batch Support | |------|-------------|---------------| | **read_content** | Read file contents | ✅ Multiple files | | **write_content** | Write/append to files | ✅ Multiple files | | **edit_file** | Surgical edits with diff output | ✅ Multiple files | | **search_files** | Regex search with context | ✅ Multiple files | | **replace_content** | Multi-file search & replace | ✅ Multiple files | ### Directory Operations | Tool | Description | Batch Support | |------|-------------|---------------| | **list_files** | List files/directories recursively | Single path | | **stat_items** | Get detailed file/directory status | ✅ Multiple items | | **create_directories** | Create directories with parents | ✅ Multiple paths | ### Management Operations | Tool | Description | Batch Support | |------|-------------|---------------| | **delete_items** | Remove files/directories | ✅ Multiple items | | **move_items** | Move/rename files/directories | ✅ Multiple items | | **copy_items** | Copy files/directories | ✅ Multiple items | ### Permission Operations | Tool | Description | Batch Support | |------|-------------|---------------| | **chmod_items** | Change POSIX permissions | ✅ Multiple items | | **chown_items** | Change ownership | ✅ Multiple items | **Key Benefit:** Tools supporting batch operations process each item individually and return detailed per-item status reports. --- ## 💡 Design Philosophy ### Core Principles 1. **Security First** - All operations confined to project root - Path traversal prevention - Permission controls built-in 2. **Efficiency Focused** - Batch processing reduces token usage - Direct API calls (no shell overhead) - Minimal communication round trips 3. **Robustness** - Per-item success/failure reporting - Detailed error messages - Zod schema validation 4. **Simplicity** - Clear, consistent API - MCP standard compliance - Easy integration --- ## 📊 Comparison with Alternatives | Feature | Filesystem MCP | Shell Commands | Other Scripts | |---------|----------------|----------------|---------------| | **Security** | ✅ Root confined | ❌ Full shell access | ⚠️ Variable | | **Token Efficiency** | ✅ Batching | ❌ One op/command | ⚠️ Variable | | **Latency** | ✅ Direct API | ❌ Shell spawn | ⚠️ Variable | | **Batch Operations** | ✅ Most tools | ❌ No | ⚠️ Maybe | | **Error Reporting** | ✅ Per-item detail | ❌ stderr parsing | ⚠️ Variable | | **Setup** | ✅ Easy (npx/Docker) | ⚠️ Secure shell setup | ⚠️ Custom | | **MCP Standard** | ✅ Full compliance | ❌ No | ⚠️ Variable | --- ## 🛠️ Tech Stack | Component | Technology | |-----------|------------| | **Language** | TypeScript (strict mode) | | **Runtime** | Node.js / Bun | | **Protocol** | Model Context Protocol (MCP) | | **Validation** | Zod schemas | | **Package Manager** | pnpm | | **Distribution** | npm + Docker Hub | --- ## 🎯 Use Cases ### AI Agent Development Enable AI agents to: - **Read project files** - Access code, configs, docs - **Edit multiple files** - Refactor across codebase - **Search codebases** - Find patterns and definitions - **Manage project structure** - Create, move, organize files ### Code Assistants Build powerful coding tools: - **Cline/Claude integration** - Direct filesystem access - **Batch refactoring** - Edit multiple files at once - **Safe operations** - Confined to project directory - **Efficient operations** - Reduce token costs ### Automation & Scripting Automate development tasks: - **File generation** - Create boilerplate files - **Project setup** - Initialize directory structures - **Batch processing** - Handle multiple files efficiently - **Content transformation** - Search and replace across files --- ## 🗺️ Roadmap **✅ Completed** - [x] Core filesystem operations (read, write, edit, etc.) - [x] Batch processing for most tools - [x] Project root security - [x] Docker image - [x] npm package - [x] Zod validation **🚀 Planned** - [ ] File watching capabilities - [ ] Streaming support for large files - [ ] Advanced filtering for `list_files` - [ ] Performance benchmarks - [ ] Compression/decompression tools - [ ] Symlink management --- ## 🤝 Contributing Contributions are welcome! Please follow these guidelines: 1. **Fork the repository** 2. **Create a feature branch** - `git checkout -b feature/my-feature` 3. **Write tests** - Ensure good coverage 4. **Follow TypeScript strict mode** - Type safety first 5. **Add documentation** - Update README if needed 6. **Submit a pull request** ### Development Setup ```bash # Clone and install git clone https://github.com/SylphxAI/filesystem-mcp.git cd filesystem-mcp pnpm install # Build pnpm run build # Watch mode (auto-rebuild) pnpm run dev ``` --- ## 🤝 Support [](https://www.npmjs.com/package/@sylphlab/filesystem-mcp) [](https://github.com/SylphxAI/filesystem-mcp/issues) - 🐛 [Bug Reports](https://github.com/SylphxAI/filesystem-mcp/issues) - 💬 [Discussions](https://github.com/SylphxAI/filesystem-mcp/discussions) - 📧 [Email](mailto:hi@sylphx.com) **Show Your Support:** ⭐ Star • 👀 Watch • 🐛 Report bugs • 💡 Suggest features • 🔀 Contribute --- ## 📄 License MIT © [Sylphx](https://sylphx.com) --- ## 🙏 Credits Built with: - [Model Context Protocol](https://docs.modelcontextprotocol.com/) - MCP standard - [Zod](https://zod.dev) - Schema validation - [TypeScript](https://typescriptlang.org) - Type safety - [pnpm](https://pnpm.io) - Package manager Special thanks to the MCP community ❤️ --- ## 📚 Publishing This repository uses GitHub Actions to automatically publish to: - **npm**: [@sylphlab/filesystem-mcp](https://www.npmjs.com/package/@sylphlab/filesystem-mcp) - **Docker Hub**: [sylphlab/filesystem-mcp](https://hub.docker.com/r/sylphlab/filesystem-mcp) Triggered on version tags (`v*.*.*`) pushed to `main` branch. **Required secrets**: `NPM_TOKEN`, `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN` --- <p align="center"> <strong>Secure. Efficient. Token-optimized.</strong> <br> _{The filesystem MCP server that saves tokens and keeps your projects safe} <br><br> <a href="https://sylphx.com">sylphx.com</a> • <a href="https://x.com/SylphxAI">@SylphxAI</a> • <a href="mailto:hi@sylphx.com">hi@sylphx.com</a> </p>