https://github.com/sylphlab/filesystem-mcp
Node.js Model Context Protocol (MCP) server providing secure, relative filesystem access for AI agents like Cline/Claude.
https://github.com/sylphlab/filesystem-mcp
ai-agent claude-ai cline filesystem mcp model-context-protocol nodejs npm roo-code typescript
Last synced: 2 months ago
JSON representation
Node.js Model Context Protocol (MCP) server providing secure, relative filesystem access for AI agents like Cline/Claude.
- Host: GitHub
- URL: https://github.com/sylphlab/filesystem-mcp
- Owner: sylphlab
- License: mit
- Created: 2025-04-04T01:43:55.000Z (2 months ago)
- Default Branch: main
- Last Pushed: 2025-04-07T20:39:22.000Z (2 months ago)
- Last Synced: 2025-04-11T00:59:17.107Z (2 months ago)
- Topics: ai-agent, claude-ai, cline, filesystem, mcp, model-context-protocol, nodejs, npm, roo-code, typescript
- Language: TypeScript
- Homepage: https://www.npmjs.com/package/@shtse8/filesystem-mcp
- Size: 801 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# 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`):_
```json
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["@sylphlab/filesystem-mcp"],
"name": "Filesystem (npx)"
}
}
}
```
_Example (`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) 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:_
```json
{
"mcpServers": {
"filesystem-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-v",
"/path/to/your/project:/app", // Mount your project to /app
"sylphlab/filesystem-mcp:latest"
],
"name": "Filesystem (Docker)"
}
}
}
```
**Remember to replace `/path/to/your/project` with the correct absolute path.**
**3. Local Build (For Development)**
1. Clone: `git clone https://github.com/sylphlab/filesystem-mcp.git`
2. Install: `cd filesystem-mcp && pnpm install` (Using pnpm now)
3. Build: `pnpm run build`
4. 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):_
```
Agent:
filesystem-mcp
read_content
{"paths": ["src/index.ts"]}
Server Response: (Content of src/index.ts)
```
## 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.)_
| Feature/Aspect | Filesystem MCP Server | Individual Shell Commands (via Agent) | Other Custom Scripts |
| :---------------------- | :-------------------- | :------------------------------------ | :------------------- |
| **Security** | High (Root Confined) | Low (Agent needs shell access) | Variable |
| **Efficiency (Tokens)** | High (Batching) | Low (One command per op) | Variable |
| **Latency** | Low (Direct API) | High (Shell spawn overhead) | Variable |
| **Batch Operations** | Yes (Most tools) | No | Maybe |
| **Error Reporting** | Detailed (Per item) | Basic (stdout/stderr parsing) | Variable |
| **Setup** | Easy (npx/Docker) | Requires secure shell setup | Custom |
## 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
1. Clone: `git clone https://github.com/sylphlab/filesystem-mcp.git`
2. Install: `cd filesystem-mcp && pnpm install`
3. Build: `pnpm run build` (compiles TypeScript to `dist/`)
4. 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.