Skip to main content
Glama
deenesjakoruzh
SylphxAI

filesystem-mcp

by SylphxAI
OverviewInspectSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

Filesystem MCP 📁

Secure filesystem operations for AI agents - Token-optimized with batch processing

npm version Docker Pulls License

Batch operations • Project root safety • Token optimized • Zod validation

Quick Start • Installation • Tools

🚀 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) 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.

Related MCP server: drupal-modules-mcp MCP Server

⚡ 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:

{ "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 (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.

{ "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

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:

{ "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

<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:

{ "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

  • Core filesystem operations (read, write, edit, etc.)

  • Batch processing for most tools

  • Project root security

  • Docker image

  • npm package

  • 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

# 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

npm GitHub Issues

Show Your Support: ⭐ Star • 👀 Watch • 🐛 Report bugs • 💡 Suggest features • 🔀 Contribute

📄 License

MIT © Sylphx

🙏 Credits

Built with:

Special thanks to the MCP community ❤️

📚 Publishing

This repository uses GitHub Actions to automatically publish to:

Triggered on version tags (v*.*.*) pushed to main branch.

Required secrets: NPM_TOKEN, DOCKERHUB_USERNAME, DOCKERHUB_TOKEN

One-click Deploy
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

Appeared in Searches

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/SylphxAI/filesystem-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server