Filesystem Mcp

Filesystem MCP

> 📖 [Installation Guide](INSTALL.md) — quick start, manual setup, and troubleshooting

> Status: Production-ready · 23 tools · Dual transport (stdio + HTTP) · Port 10742 > Reliability: Self-cleaning startup — kills orphaned stdio processes from stale IDE sessions

A FastMCP 3.2.0+ compliant MCP server using the portmanteau pattern for comprehensive file system operations, Git repository management, and Docker container management with concurrency safety.

> [!IMPORTANT] > Dual Architecture: Filesystem MCP operates as both a high-concurrency stdio/HTTP MCP Server and a dedicated React Webapp (Port 10702) for real-time visualization and management.

Quick Start

git clone https://github.com/sandraschi/filesystem-mcp
cd filesystem-mcp
just

This opens an interactive dashboard showing all available commands. Run just bootstrap to install dependencies, then just serve or just dev to start.

Manual Setup

If you don't have just installed:

Deployment & Security

Built with modern Python patterns, enterprise-grade security, and extensive testing for professional deployment.

Features

File System Operations (20+ Tools)

• Concurrency-Safe Operations: Atomic file writes with proper locking for multi-client access
• Basic Operations: Read, write, list, copy, move, and delete files/directories
• Advanced Analysis: Find large files, duplicate detection, directory size calculation
• File Comparison: Side-by-side diff comparison with unified format
• Content Search: Grep pattern matching, line-based reading, log extraction
• Batch Operations: Process multiple files simultaneously
• Path Management: Secure path validation with configurable restrictions
• Metadata Analysis: Comprehensive file information with type detection
• Universal Connect: FastMCP 3.2.0+ support for simultaneous stdio + HTTP access

Docker Container Management

• Container Operations
• List, create, start, stop, and remove containers
• Execute commands inside running containers
• Stream container logs with filtering options
• Monitor container resource usage and statistics
• Inspect container details and configuration

• Image Management
• List available Docker images
• Pull, build, and remove images
• Inspect image details and history

• Network & Volume Management
• Create and manage Docker networks
• Manage Docker volumes and bind mounts
• Configure container networking

• Docker Compose Support
• Deploy and manage multi-container applications
• Scale services up and down
• View service logs and status

Git Repository Management

• Clone repositories with branch and depth control
• Get repository status (staged, unstaged, untracked changes)
• Commit changes with custom messages
• Read repository structure and file contents
• Manage branches and remotes

System Tools & Help

• Multilevel Help System: Hierarchical documentation with portmanteau tool examples and use cases
• System Status Tool: Comprehensive system monitoring with resource usage metrics
• Interactive Guidance: Context-aware help with parameter validation and suggestions

Advanced Features

• FastMCP 3.2.0+ Compliance: Modern tool registration with @app.tool() decorators
• Portmanteau Pattern: Consolidated tool interfaces reducing complexity while maintaining full functionality
• Enterprise Security: Path traversal protection, permission validation, audit trails
• Extensive Testing: Unit, integration, and performance tests with 80%+ coverage
• MCPB Packaging: Professional drag-and-drop installation for Claude Desktop
• Structured Logging: Comprehensive logging with file output and monitoring
• Async Operations: Full async/await support for optimal concurrency
• Pydantic V2: Modern data validation with field_validator and ConfigDict
• Multilevel Help System: Interactive guidance with portmanteau tool examples and use cases
• System Monitoring: Resource usage tracking and performance metrics
• Cross-Platform: Windows, macOS, and Linux support

Installation

Prerequisites

• uv installed (RECOMMENDED)
• Python 3.12+

Quick Start

Run immediately via uvx:

uvx filesystem-mcp

Claude Desktop Integration

Add to your claude_desktop_config.json:

"mcpServers": {
  "filesystem-mcp": {
    "command": "uv",
    "args": ["--directory", "D:/Dev/repos/filesystem-mcp", "run", "filesystem-mcp"]
  }
}

Prerequisites

• Python 3.12+ (FastMCP 3.2.0+ requirement)
• Docker Engine (for container operations)
• Git (for repository operations)

PyPI Package Install (RECOMMENDED)

Fastest Installation - Production Ready:

pip install filesystem-mcp

Claude Desktop Integration:

• Open Claude Desktop
• Settings MCP Servers
• Add new MCP server:

``json { "mcpServers": { "filesystem-mcp": { "command": "filesystem-mcp" } } } ``

Claude Desktop MCPB Package

1. Download the filesystem-mcp.mcpb package from Releases
2. Drag & Drop the file to Claude Desktop
3. Configure settings when prompted (working directory, timeouts, etc.)
4. Install dependencies separately (see below)
5. Start using 57+ professional tools immediately

Installation

Prerequisites

• uv installed (RECOMMENDED)
• Python 3.12+

Quick Start

Run immediately via uvx:

uvx filesystem-mcp

Claude Desktop Integration

Add to your claude_desktop_config.json:

"mcpServers": {
  "filesystem-mcp": {
    "command": "uv",
    "args": ["--directory", "D:/Dev/repos/filesystem-mcp", "run", "filesystem-mcp"]
  }
}

Installation

Prerequisites

• uv installed (RECOMMENDED)
• Python 3.12+

Quick Start

Run immediately via uvx:

uvx filesystem-mcp

Claude Desktop Integration

Add to your claude_desktop_config.json:

"mcpServers": {
  "filesystem-mcp": {
    "command": "uv",
    "args": ["--directory", "D:/Dev/repos/filesystem-mcp", "run", "filesystem-mcp"]
  }
}

HTTP/HTTPS Mode (For Web Apps)

For web applications or custom MCP clients, run the server in HTTP mode:

# Set environment variables
export MCP_TRANSPORT=http
export MCP_HOST=127.0.0.1  # or 0.0.0.0 for all interfaces
export MCP_PORT=8000

# Run the server
python -m filesystem_mcp

Or use uvicorn directly with the ASGI app:

from filesystem_mcp import http_app
import uvicorn

# Get ASGI app
asgi_app = http_app()

# Run with uvicorn
uvicorn.run(asgi_app, host="127.0.0.1", port=8000)

Or via command line:

uvicorn filesystem_mcp:http_app --host 127.0.0.1 --port 8000

The MCP endpoint will be available at: http://127.0.0.1:8000/mcp/

Quick test:

curl http://127.0.0.1:8000/mcp/

Manual Claude Desktop Configuration

For manual installation or other MCP clients, add to your Claude Desktop configuration file (claude_desktop_config.json):

Windows:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "python",
      "args": ["-m", "filesystem_mcp"],
      "env": {
        "PYTHONPATH": "D:\\path\\to\\filesystem-mcp\\src",
        "PYTHONUNBUFFERED": "1",
        "FASTMCP_LOG_LEVEL": "INFO"
      },
      "cwd": "D:\\path\\to\\your\\working\\directory"
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "python",
      "args": ["-m", "filesystem_mcp"],
      "env": {
        "PYTHONPATH": "/path/to/filesystem-mcp/src",
        "PYTHONUNBUFFERED": "1",
        "FASTMCP_LOG_LEVEL": "INFO"
      },
      "cwd": "/path/to/your/working/directory"
    }
  }
}

Configuration Notes:

• Replace D:\\path\\to\\filesystem-mcp\\src with the actual path to your cloned repository's src directory
• Set cwd to your preferred working directory for file operations
• The server supports the following optional environment variables:
• MCP_TRANSPORT: Set to "http" for HTTP mode, "stdio" for stdio mode (default: "stdio")
• MCP_HOST: Host address for HTTP mode (default: "127.0.0.1")
• MCP_PORT: Port number for HTTP mode (default: 8000)
• FASTMCP_LOG_LEVEL: Set to DEBUG, INFO, WARNING, or ERROR
• GIT_USERNAME: Default Git username for commits
• GIT_EMAIL: Default Git email for commits

Installation

Prerequisites

• uv installed (RECOMMENDED)
• Python 3.12+

Quick Start

Run immediately via uvx:

uvx filesystem-mcp

Claude Desktop Integration

Add to your claude_desktop_config.json:

"mcpServers": {
  "filesystem-mcp": {
    "command": "uv",
    "args": ["--directory", "D:/Dev/repos/filesystem-mcp", "run", "filesystem-mcp"]
  }
}

Help System & Status Tools

System Operations (portmanteau)

Unified system tool with 20+ operations:

• Help: get_help - Multilevel help system with tool documentation
• Status: get_system_status - Comprehensive system monitoring
• Resources: get_resource_usage, get_cpu_info, get_memory_info, get_disk_usage
• Processes: get_process_info - Process monitoring and management
• Network: get_network_info - Network interface information
• System Info: get_system_info, get_hardware_info, get_software_info
• Environment: get_environment_info, get_locale_info, get_time_info
• Security: get_security_info - Basic security information
• Performance: get_performance_metrics - System performance monitoring

# Get comprehensive help
result = system_operations("get_help", category="filesystem")

# Monitor system status
result = system_operations("get_system_status", include_processes=True, include_disk=True)

# Get resource usage
result = system_operations("get_resource_usage")

Multilevel Help System

Get comprehensive guidance for all portmanteau tools:

# Overview of all categories and tools
system_operations("get_help")

# Detailed help for filesystem operations
system_operations("get_help", category="filesystem")

# Specific tool documentation with examples
system_operations("get_help", category="filesystem", tool_name="filesystem_operations")

Help Categories:

• filesystem - File reading, writing, directory management, search, analysis
• docker - Container, image, network, and volume management
• repository - Git repository operations (clone, commit, branch, merge, etc.)
• system - System monitoring, status, and help functionality

System Status Monitoring

Monitor system resources and server health:

# Comprehensive system status
system_operations("get_system_status")

# Resource monitoring only
system_operations("get_system_status", include_processes=True, include_disk=True)

# Network and system info
system_operations("get_system_status", include_network=True)

Status Metrics:

• CPU usage (physical/logical cores, frequency, load)
• Memory statistics (total, available, usage percentage)
• Disk usage (total, used, free space)
• Process information (top CPU consumers)
• Network interfaces (IP addresses, status)
• Server health (FastMCP version, tool count, status)

Usage

Starting the Server

# Start the MCP server (default: http://0.0.0.0:8000)
python -m filesystem_mcp

# With custom host and port
python -m filesystem_mcp --host 127.0.0.1 --port 8080

# With debug mode enabled
python -m filesystem_mcp --debug

Available Portmanteau Tools

Filesystem Operations (portmanteau)

Unified filesystem tool with 20+ operations:

• file_ops: Comprehensive file management (read_file, write_file, edit_file, move_file, undo_edit).
• Honed Editing: Support for Regex, Multi-occurrence, Indentation Normalization, and Atomic Batch Edits.
• Reversion: Rapid undo capability via .bak file restoration.
• calculate_directory_size, find_duplicate_files, find_large_files
• find_empty_directories, compare_files, read_multiple_files
• move_file, read_file_lines, search_files

edit_file

Precise text replacement with context validation and advanced matching.

Parameters:

• path (str): Target file path.
• old_string (str): Text to find.
• new_string (str): Replacement text.
• allow_multiple (bool): If true, replaces all occurrences. Default: false.
• is_regex (bool): If true, treats old_string as a regex pattern. Default: false.
• ignore_whitespace (bool): If true, matches regardless of indentation. Default: false.
• replacements (list): Batch mode! List of {old_string, new_string} for atomic multi-chunk edits.

undo_edit

Reverts the most recent edit to a file by restoring its .bak backup.

Parameters:

• path (str): Target file path.

# Read a file
result = filesystem_operations("read_file", path="README.md")

# List directory contents
result = filesystem_operations("list_directory", path=".", recursive=True)

# Search for files
result = filesystem_operations("search_files", directory_path=".", pattern="*.py")

Docker Operations (portmanteau)

Unified Docker tool with 25+ operations:

• Container: list_containers, get_container, create_container, start_container, stop_container, restart_container, remove_container, container_exec, container_logs, container_stats
• Images: list_images, get_image, pull_image, build_image, remove_image, prune_images
• Networks: list_networks, get_network, create_network, remove_network, prune_networks
• Volumes: list_volumes, get_volume, create_volume, remove_volume, prune_volumes
• Compose: compose_up, compose_down, compose_ps, compose_logs, compose_config, compose_restart

# List running containers
result = docker_operations("list_containers")

# Create and start a container
result = docker_operations("create_container", image="nginx:latest", name="web", ports={"80/tcp": 8080})
result = docker_operations("start_container", container_id="web")

# Get container logs
result = docker_operations("container_logs", container_id="web", tail=100)

Repository Operations (portmanteau)

Unified Git tool with 30+ operations:

• Basic: clone_repo, get_repo_status, commit_changes, read_repo
• Branching: create_branch, switch_branch, merge_branch, delete_branch, list_branches
• Remotes: push_changes, pull_changes, fetch_updates, list_remotes, add_remote, remove_remote
• History: get_commit_history, show_commit, diff_changes, blame_file, get_file_history
• Advanced: stash_changes, apply_stash, list_stashes, create_tag, list_tags, delete_tag
• Operations: revert_commit, reset_to_commit, cherry_pick, rebase_branch, resolve_conflicts

# Clone a repository
result = repository_operations("clone_repo", repo_url="https://github.com/user/repo.git", target_dir="./project")

# Get repository status
result = repository_operations("get_repo_status", repo_path="./project")

# Commit changes
result = repository_operations("commit_changes", repo_path="./project", message="Add new feature", add_all=True)

Developer Tools

Unified Developer Toolkit - One tool with 10 specialized commands:

| Command | Description | Key Parameters | |---------|-------------|----------------| | analyze_dependencies | Analyze project dependencies from package managers | path | | analyze_imports | Analyze Python import statements and dependencies | path, recursive, max_results | | analyze_project | Detect project type, frameworks, and structure | `p

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: sandraschi
• Source: sandraschi/filesystem-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.