Filesystem MCP Server (@sylphlab/filesystem-mcp)
[](https://badge.fury.io/js/%40sylphlab%2Ffilesystem-mcp)
[](https://hub.docker.com/r/sylphlab/filesystem-mcp)
**Empower your AI agents (like Cline/Claude) 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, operating safely within a defined project root directory.
Installation
There are several ways to use the Filesystem MCP Server:
**1. Recommended: `npx` (or `bunx`) via MCP Host Configuration**
The simplest way is via `npx` or `bunx`, configured directly in your MCP host environment (e.g., Roo/Cline's `mcp_settings.json`). This ensures you always use the latest version from npm without needing local installation or Docker.
_Example (`npx`):_
_Example (`bunx`):_
**Important:** The server uses its own Current Working Directory (`cwd`) as the project root. Ensure your MCP Host (e.g., Cline/VSCode) is configured to launch the command with the `cwd` set to your active project's root directory.
**2. Docker**
Use the official Docker image for containerized environments.
_Example MCP Host Configuration:_
**Remember to replace `/path/to/your/project` with the correct absolute path.**
**3. Local Build (For Development)**
- Clone: `git clone https://github.com/sylphlab/filesystem-mcp.git`
- Install: `cd filesystem-mcp && pnpm install` (Using pnpm now)
- Build: `pnpm run build`
- Configure MCP Host: ```json { "mcpServers": { "filesystem-mcp": { "command": "node", "args": ["/path/to/cloned/repo/filesystem-mcp/dist/index.js"], // Updated build dir "name": "Filesystem (Local Build)" } } } ``` **Note:** Launch the `node` command from the directory you intend as the project root.
Quick Start
Once the server is configured in your MCP host (see Installation), your AI agent can immediately start using the filesystem tools.
_Example Agent Interaction (Conceptual):_
Why Choose This Project?
- ** Secure & Convenient Project Root Focus:** Operations confined to the project root (`cwd` at launch).
- ** Optimized & Consolidated Tools:** Batch operations reduce AI-server round trips, saving tokens and latency. Reliable results for each item in a batch.
- ** Easy Integration:** Quick setup via `npx`/`bunx`.
- ** Containerized Option:** Available as a Docker image.
- ** Comprehensive Functionality:** Covers a wide range of filesystem tasks.
- ** Robust Validation:** Uses Zod schemas for argument validation.
Performance Advantages
_(Placeholder: Add benchmark results and comparisons here, demonstrating advantages over alternative methods like individual shell commands.)_
- **Batch Operations:** Significantly reduces overhead compared to single operations.
- **Direct API Usage:** More efficient than spawning shell processes for each command.
- _(Add specific benchmark data when available)_
Features
This server equips your AI agent with a powerful and efficient filesystem toolkit:
- **Explore & Inspect (`list_files`, `stat_items`):** List files/directories (recursive, stats), get detailed status for multiple items.
- **Read & Write Content (`read_content`, `write_content`):** Read/write/append multiple files, creates parent directories.
- **Precision Editing & Searching (`edit_file`, `search_files`, `replace_content`):** Surgical edits (insert, replace, delete) across multiple files with indentation preservation and diff output; regex search with context; multi-file search/replace.
- **Manage Directories (`create_directories`):** Create multiple directories including intermediate parents.
- **Delete Safely (`delete_items`):** Remove multiple files/directories recursively.
- **Move & Copy (`move_items`, `copy_items`):** Move/rename/copy multiple files/directories.
- **Control Permissions (`chmod_items`, `chown_items`):** Change POSIX permissions and ownership for multiple items.
**Key Benefit:** All tools accepting multiple paths/operations process each item individually and return a detailed status report.
Design Philosophy
_(Placeholder: Explain the core design principles.)_
- **Security First:** Prioritize preventing access outside the project root.
- **Efficiency:** Minimize communication overhead and token usage for AI interactions.
- **Robustness:** Provide detailed results and error reporting for batch operations.
- **Simplicity:** Offer a clear and consistent API via MCP.
- **Standard Compliance:** Adhere strictly to the Model Context Protocol.
Comparison with Other Solutions
_(Placeholder: Objectively compare with alternatives.)_
[object Object] | [object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] | [object Object] |
Future Plans
_(Placeholder: List upcoming features or improvements.)_
- Explore file watching capabilities.
- Investigate streaming support for very large files.
- Enhance performance for specific operations.
- Add more advanced filtering options for `list_files`.
Documentation
_(Placeholder: Add link to the full documentation website once available.)_
Full documentation, including detailed API references and examples, will be available at: [Link to Docs Site]
Contributing
Contributions are welcome! Please open an issue or submit a pull request on the [GitHub repository](https://github.com/sylphlab/filesystem-mcp).
License
This project is released under the [MIT License](LICENSE).
Development
- Clone: `git clone https://github.com/sylphlab/filesystem-mcp.git`
- Install: `cd filesystem-mcp && pnpm install`
- Build: `pnpm run build` (compiles TypeScript to `dist/`)
- Watch: `pnpm run dev` (optional, recompiles on save)
Publishing (via GitHub Actions)
This repository uses GitHub Actions (`.github/workflows/publish.yml`) to automatically publish the package to [npm](https://www.npmjs.com/package/@sylphlab/filesystem-mcp) and build/push a Docker image to [Docker Hub](https://hub.docker.com/r/sylphlab/filesystem-mcp) on pushes of version tags (`v*.*.*`) to the `main` branch. Requires `NPM_TOKEN`, `DOCKERHUB_USERNAME`, and `DOCKERHUB_TOKEN` secrets configured in the GitHub repository settings.