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

Related MCP server: File Operations MCP Server

🚀 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

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

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

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.