ceciliomichael/mcp-filesystem

MCP Filesystem Server

A comprehensive Model Context Protocol (MCP) server providing advanced filesystem operations with intelligent features for AI-assisted development workflows.

Features

🔧 Core Tools

• batch_read - Read multiple files efficiently in a single operation
• rename_file - Rename files with safety checks
• move_file - Move files with automatic directory creation
• check_structure - Display project structure with smart filtering
• run_command - Execute commands with Python virtual environment auto-activation

🚀 Advanced Capabilities

• Smart Virtual Environment Detection - Automatically activates Python .venv when detected
• Cross-Platform Support - Works on Windows, macOS, and Linux
• Intelligent Filtering - Uses .checkignore files + built-in patterns for clean structure views
• Command Prohibition - Prevents file management command overlap between tools
• Enhanced Quote Handling - Proper execution of complex commands with quoted arguments
• Clean Output Format - Focused, minimal output for better AI integration

Quick Start

Installation

npm install
npm run build

Configuration

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "/absolute/path/to/dist/index.js"
      ],
      "env": {}
    }
  }
}

Tool Documentation

📄 batch_read

Read multiple files concurrently with automatic encoding detection.

{
  projectPath: "C:/project",
  relativePaths: ["src/index.ts", "package.json", "README.md"]
}

Features:

• Concurrent file reading for performance
• UTF-8 and binary (base64) support
• Empty file detection ([EMPTY] indicator)
• Graceful error handling for missing files

🔄 rename_file

Safely rename files with conflict detection.

{
  projectPath: "C:/project", 
  currentPath: "src/oldname.js",
  newName: "newname.js"
}

Safety Features:

• Source file existence validation
• Destination conflict prevention
• Clear success/error feedback

📁 move_file

Move files with automatic directory creation.

{
  projectPath: "C:/project",
  sourcePath: "src/component.tsx", 
  destinationPath: "src/components/component.tsx"
}

Features:

• Automatic parent directory creation
• Conflict detection and prevention
• Cross-directory moves

🌳 check_structure

Display clean project structure with intelligent filtering.

{
  projectPath: "C:/project"
}

Smart Filtering:

• Built-in ignore patterns (node_modules, .git, dist, etc.)
• Custom .checkignore file support
• Empty directory detection
• Clean tree visualization

.checkignore Format

# Comments start with #
temp/
*.tmp
*.log
debug/

💻 run_command

Execute development commands with Python virtual environment auto-activation.

{
  projectPath: "C:/project",
  command: "npm test"
}

Features:

• Auto venv activation - Detects .venv and activates automatically
• Cross-platform - Windows and Unix support
• Quote handling - Proper execution of complex quoted commands
• Command prohibition - Blocks file management commands (use dedicated tools)

Prohibited Commands:

• File reading: cat, type, more, etc. → Use batch_read
• File moving: mv, move, ren → Use rename_file/move_file
• File listing: dir, ls, tree → Use check_structure

Examples

Python Development Workflow

// Check project structure
{ projectPath: "C:/python-project" }

// Read configuration files  
{
  projectPath: "C:/python-project",
  relativePaths: ["requirements.txt", "setup.py", "src/main.py"]
}

// Run tests (auto-activates .venv)
{
  projectPath: "C:/python-project", 
  command: "pytest tests/ -v"
}

// Install packages (in venv)
{
  projectPath: "C:/python-project",
  command: "pip install requests"
}

Node.js Development Workflow

// Build project
{
  projectPath: "C:/node-project",
  command: "npm run build"
}

// Run tests
{
  projectPath: "C:/node-project", 
  command: "npm test"
}

// Lint code
{
  projectPath: "C:/node-project",
  command: "npx eslint src/ --fix"
}

Technical Details

Virtual Environment Detection

The server automatically detects Python virtual environments:

• Windows: .venv\Scripts\activate.bat
• Unix/Linux: .venv/bin/activate

When detected, all Python commands are executed within the virtual environment context.

Error Handling

All tools provide comprehensive error handling:

• File not found - Clear error messages with full paths
• Permission denied - Specific access error reporting
• Command failures - Exit codes and stderr capture
• Validation errors - Pre-execution checks prevent issues

Performance

• Concurrent operations - Multiple files read simultaneously
• Smart filtering - Reduces unnecessary filesystem traversal
• Efficient command execution - Minimal overhead for command operations

Development

Building

npm run build

Testing

npm run dev  # Build and start

Project Structure

src/
├── index.ts          # Main MCP server implementation
package.json          # Dependencies and scripts
tsconfig.json         # TypeScript configuration
.checkignore          # Structure filtering patterns
README.md            # This documentation

License

MIT License

Contributing

Contributions welcome! Please ensure all tools maintain the clean, focused output format and comprehensive error handling standards.