MCP Server Filesystem

An enhanced Model Context Protocol (MCP) filesystem server that fixes common limitations and adds powerful features missing from standard implementations.

🌟 Key Features

✅ Fixed Issues

Glob Pattern Search: Properly supports patterns like *pipeline*, *.js, **/*test*
Head + Tail Support: Read first N lines AND last M lines simultaneously (fixes "Cannot specify both head and tail parameters")
Enhanced File Operations: Complete file editing with diff preview

🚀 Core Tools

read_file - Read files with head/tail support
read_multiple_files - Batch file reading
write_file - Create/overwrite files
delete_file - NEW Delete files/directories (with recursive option)
edit_file - ENHANCED Line-based editing with intelligent syntax validation and diff preview
search_files - FIXED glob pattern search
list_directory - Directory listing
create_directory - Directory creation
get_file_info - File metadata
move_file - File/directory moving
run_command - NEW Shell command execution
list_allowed_directories - Security transparency

🚀 Quick Start

Installation Options

Option 1: NPM Package (Recommended)

# Install globally
npm install -g @redf0x1/mcp-server-filesystem

# Or use with npx (no installation needed)
npx @redf0x1/mcp-server-filesystem /path/to/your/workspace

Option 2: From Source

git clone https://github.com/redf0x1/mcp-server-filesystem.git
cd mcp-server-filesystem
npm install

Usage

With NPX (Recommended):

npx @redf0x1/mcp-server-filesystem /path/to/allowed/directory

Direct execution:

node server-filesystem.js /path/to/allowed/directory

With npm script:

npm start  # Uses ./workspace as default

MCP Client Configurations

Important: The cwd (current working directory) parameter is required for proper server operation. It ensures the server starts from the correct directory and can resolve relative paths properly.

VS Code with MCP Extension

Add to your mcp.json:

With NPX (Recommended):

{
  "servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@redf0x1/mcp-server-filesystem",
        "/home/user/projects",
        "/home/user/documents"
      ]
    }
  },
  "inputs": []
}

With local installation:

{
  "servers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/path/to/server-filesystem.js",
        "/home/user/projects",
        "/home/user/documents"
      ],
      "cwd": "/path/to/mcp-server-filesystem"
    }
  },
  "inputs": []
}

Cursor IDE

Add to your MCP settings:

With NPX:

{
  "mcp": {
    "servers": {
      "enhanced-filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@redf0x1/mcp-server-filesystem",
          "/Users/username/workspace",
          "/Users/username/scripts"
        ]
      }
    }
  }
}

With local installation:

{
  "mcp": {
    "servers": {
      "enhanced-filesystem": {
        "command": "node",
        "args": [
          "/path/to/server-filesystem.js",
          "/Users/username/workspace",
          "/Users/username/scripts"
        ],
        "cwd": "/path/to/mcp-server-filesystem"
      }
    }
  }
}

Cline (Claude for VSCode)

Configuration in settings:

With NPX:

{
  "cline.mcp.servers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y", 
        "@redf0x1/mcp-server-filesystem",
        "/workspace/current-project",
        "/workspace/shared-libs"
      ],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

With local installation:

{
  "cline.mcp.servers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/path/to/server-filesystem.js",
        "/workspace/current-project",
        "/workspace/shared-libs"
      ],
      "cwd": "/path/to/mcp-server-filesystem",
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}

Windsurf AI Editor

Add to MCP configuration:

With NPX:

{
  "servers": {
    "filesystem-enhanced": {
      "command": "npx",
      "args": [
        "-y",
        "@redf0x1/mcp-server-filesystem",
        "/home/developer/projects",
        "/tmp/workspace"
      ],
      "timeout": 30000
    }
  }
}

With local installation:

{
  "servers": {
    "filesystem-enhanced": {
      "command": "node",
      "args": [
        "/opt/mcp-tools/server-filesystem.js",
        "/home/developer/projects",
        "/tmp/workspace"
      ],
      "cwd": "/opt/mcp-tools",
      "timeout": 30000
    }
  }
}

Generic MCP Client

Standard configuration format:

#### Generic MCP Client

**With NPX (Recommended):**
```json
{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": [
          "-y",
          "@redf0x1/mcp-server-filesystem",
          "/path/to/allowed/directory1",
          "/path/to/allowed/directory2"
        ]
      }
    }
  }
}

With local installation:

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "node",
        "args": [
          "./server-filesystem.js",
          "/path/to/allowed/directory1",
          "/path/to/allowed/directory2"
        ],
        "cwd": "/path/to/server/directory"
      }
    }
  }
}

Docker Integration

For containerized environments:

With NPX:

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/host/projects,dst=/container/projects",
        "--mount", "type=bind,src=/host/data,dst=/container/data,ro",
        "node:18-alpine",
        "sh", "-c",
        "npx @redf0x1/mcp-server-filesystem /container/projects /container/data"
      ]
    }
  }
}

With global installation:

{
  "mcpServers": {
    "filesystem": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--mount", "type=bind,src=/host/projects,dst=/container/projects",
        "--mount", "type=bind,src=/host/data,dst=/container/data,ro",
        "node:18-alpine",
        "sh", "-c",
        "npm install -g @redf0x1/mcp-server-filesystem && mcp-server-filesystem /container/projects /container/data"
      ]
    }
  }
}

NPM Global Installation

Install globally for easier access:

npm install -g @redf0x1/mcp-server-filesystem
mcp-server-filesystem /your/project/path

🛠️ Enhanced Features

1. Smart Head + Tail Reading

Before (Standard):

{
  "path": "large-file.txt",
  "head": 10,
  "tail": 5
}

❌ Error: Cannot specify both head and tail parameters simultaneously

After (Complete):

{
  "path": "large-file.txt", 
  "head": 10,
  "tail": 5
}

✅ Result:

Line 1: ...
Line 2: ...
...
Line 10: ...
... (middle content omitted) ...
Line 96: ...
Line 97: ...
...
Line 100: ...

2. Fixed Glob Pattern Search

Before (Standard):

{
  "path": "/project",
  "pattern": "*config*"
}

❌ Only finds exact matches, ignores glob patterns

After (Complete):

{
  "path": "/project", 
  "pattern": "*config*"
}

✅ Finds: webpack.config.js, app-config.json, config/database.php, etc.

Supported patterns:

*.js - All JavaScript files
*test* - Files containing "test"
**/*config* - Config files in any subdirectory
src/**/*.ts - TypeScript files in src/

3. Intelligent File Editing with Syntax Validation

Enhanced validation for multiple file types:

{
  "path": "app.ts",
  "edits": [
    {
      "oldText": "const port = 3000;",
      "newText": "const port: number = process.env.PORT || 3000;"
    }
  ],
  "dryRun": true,
  "skipValidation": false
}

Supported file types for validation:

JavaScript/JSX - Bracket matching, semicolon checking, control structure validation
TypeScript/TSX - Type annotation validation, interface/type definition checking
JSON - Complete JSON syntax validation
YAML - Indentation, structure, and syntax validation
XML/HTML - Tag matching and structure validation

Smart error handling:

❌ VALIDATION FAILED for typescript file: app.ts

Error: Unclosed '{' starting at line 15, column 23

🔧 SUGGESTED FIXES:
1. Check for missing/extra brackets, braces, or parentheses
2. Verify proper line endings and indentation
3. Ensure all strings are properly quoted
4. Check for missing semicolons (JavaScript/TypeScript)
5. Validate type annotations (TypeScript)
6. Use skipValidation=true only if you're certain the syntax is correct

📝 TIP: Preview your changes with dryRun=true first

Advanced features:

Pre-edit validation - Checks syntax before applying changes
Detailed error messages - Specific line/column error reporting
File type detection - Automatic detection based on extension
Smart suggestions - Context-aware fix recommendations
Dry run mode - Preview changes with dryRun=true
Validation bypass - Use skipValidation=true for edge cases

4. Secure Command Execution

{
  "command": "npm install lodash",
  "workingDirectory": "/workspace/project",
  "timeout": 30000,
  "includeStderr": true
}

Execute shell commands safely within allowed directories:

Git operations: git status, git add ., git commit
Package management: npm install, pip install, composer install
Build tools: webpack build, tsc, make
File operations: find, grep, ls -la

Security features:

Commands run only in allowed directories
Configurable timeout protection
Both stdout and stderr capture
Environment isolation

5. Safe File/Directory Deletion

{
  "path": "/workspace/temp-file.txt"
}

Delete files safely:

{
  "path": "/workspace/temp-directory",
  "recursive": true
}

Delete directories with contents:

Single files: Safe file deletion with validation
Empty directories: Remove empty directories only
Recursive deletion: Remove directories and all contents (use with caution)
Error handling: Clear messages for non-existent or protected files

📁 Project Structure

mcp-server-filesystem/
├── server-filesystem.js          # Main server file
├── package.json                  # Dependencies and scripts
├── mcp-config.json              # MCP configuration example
├── README.md                    # This file
└── workspace/                   # Demo workspace
    ├── demo.txt                 # Sample text file
    ├── deploy-pipeline.yml      # Sample YAML
    └── pipeline-config.js       # Sample JS config

🔧 Development

Configuration Best Practices

Always specify cwd:

{
  "servers": {
    "filesystem": {
      "command": "node",
      "args": ["/absolute/path/to/server-filesystem.js", "/workspace"],
      "cwd": "/absolute/path/to/server/directory"  // ⭐ Required!
    }
  }
}

Why cwd is important:

Ensures server starts from correct directory
Resolves relative paths properly
Prevents "Cannot find module" errors
Required for proper dependency loading

Example working config:

{
  "servers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/root/server-filesystem/server-filesystem.js",
        "/var/www/projects",
        "/home/user/documents"
      ],
      "cwd": "/root/server-filesystem"
    }
  }
}

Local Development

npm run dev  # Starts server with ./workspace

Common Usage Examples

Web Development:

node server-filesystem.js /home/user/websites /home/user/config

Data Science:

node server-filesystem.js /data/datasets /notebooks /scripts

DevOps:

node server-filesystem.js /infrastructure /deployments /monitoring

Mobile Development:

node server-filesystem.js /android-projects /ios-projects /shared-assets

Testing Tools

Test individual tools using your MCP client or create custom test scripts.

🔒 Security

Path Validation: All operations restricted to allowed directories
Symlink Protection: Prevents symlink-based path traversal
Atomic Operations: File writes use atomic rename for consistency
Input Sanitization: All inputs validated with Zod schemas
Command Isolation: Shell commands run with restricted permissions

🚨 Troubleshooting

Common Issues

Server won't start:

# Check Node.js version
node --version  # Should be >=18.0.0

# Verify dependencies
npm install

# Check directory permissions
ls -la /path/to/allowed/directory

"Cannot find module" error:

Verify the server file path in your config: /path/to/server-filesystem.js
Ensure cwd points to the directory containing the server file
Check file permissions: ls -la /path/to/server-filesystem.js

Path access denied:

Ensure directories exist and are readable
Check symlink targets are within allowed paths
Verify absolute paths in configuration
Make sure cwd is set correctly in your MCP configuration

Glob patterns not working:

# ✅ Correct patterns
"*.js"           # All JS files
"**/test/*"      # Test files in any subdirectory
"*config*"       # Files containing "config"

# ❌ Incorrect patterns
"*.js*"          # Too broad
"test"           # Too specific

Performance Tips

Use specific glob patterns to reduce search time
Limit the number of allowed directories
Use head/tail for large files instead of reading entire content
Enable excludePatterns in search operations

📋 Requirements

Node.js: 18.0.0 or higher
Dependencies:
- @modelcontextprotocol/sdk
- minimatch (for glob patterns)
- diff (for file editing)
- zod (for validation)

🤝 Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built on top of the Model Context Protocol
Inspired by the official MCP filesystem server
Enhanced to solve real-world limitations

🆚 What's Different?

This server fixes several critical issues found in standard MCP filesystem implementations:

Issue	Standard Behavior	✅ Our Solution
Glob patterns	`search_files` uses simple `includes()`	Uses `minimatch` for proper glob support
Head + Tail	"Cannot specify both parameters" error	Smart combination with separator
File editing	No diff preview	Git-style diff before applying changes
Syntax validation	No validation before file write	Intelligent validation for JS/TS/JSON/YAML/XML
Edit error feedback	Generic "operation failed" messages	Detailed syntax error with line/column info
Command execution	Not available	Secure shell command execution
File deletion	Basic `unlink()` only	Safe deletion with recursive option and validation
Error handling	Basic error messages	Detailed context and troubleshooting

Performance improvements:

Multi-strategy pattern matching for better search results
Atomic file operations for data consistency
Memory-efficient head/tail reading for large files
Safe recursive deletion with proper validation
Debug logging for troubleshooting

Additional features not found in standard implementations:

Combined head+tail reading for file previews
Git-style diff preview before file edits
Intelligent syntax validation for JavaScript, TypeScript, JSON, YAML, XML/HTML
Smart error reporting with line/column precision and fix suggestions
Secure command execution within allowed directories
Multiple glob pattern strategies for comprehensive search
Enhanced error messages with context and solutions
Model-friendly validation feedback to help AI assistants learn from syntax errors

Note: This server addresses specific limitations found in standard MCP filesystem implementations. If you need basic filesystem operations without the enhanced features, consider using the official @modelcontextprotocol/server-filesystem package.

Name		Name	Last commit message	Last commit date
Latest commit History 8 Commits
workspace		workspace
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
mcp-config-npx.json		mcp-config-npx.json
mcp-config.json		mcp-config.json
package-lock.json		package-lock.json
package.json		package.json
server-filesystem.js		server-filesystem.js

License

redf0x1/MCP-Server-Filesystem

Folders and files

Latest commit

History

Repository files navigation

MCP Server Filesystem

🌟 Key Features

✅ Fixed Issues

🚀 Core Tools

🚀 Quick Start

Installation Options

Usage

MCP Client Configurations

VS Code with MCP Extension

Cursor IDE

Cline (Claude for VSCode)

Windsurf AI Editor

Generic MCP Client

Docker Integration

NPM Global Installation

🛠️ Enhanced Features

1. Smart Head + Tail Reading

2. Fixed Glob Pattern Search

3. Intelligent File Editing with Syntax Validation

4. Secure Command Execution

5. Safe File/Directory Deletion

📁 Project Structure

🔧 Development

Configuration Best Practices

Local Development

Common Usage Examples

Testing Tools

🔒 Security

🚨 Troubleshooting

Common Issues

Performance Tips

📋 Requirements

🤝 Contributing

📝 License

🙏 Acknowledgments

🆚 What's Different?

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Languages

Packages