Filesystem MCP

📖 Installation Guide — quick start, manual setup, and troubleshooting

Status: Production-ready · 24 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, content search, and code intelligence with concurrency safety. Git lives in git-github-mcp; Docker is deprecated here in favor of docker-mcp.

[!IMPORTANT] Dual Architecture: Filesystem MCP operates as both a high-concurrency stdio/HTTP MCP Server and a dedicated React Webapp (Port 10743) 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:

What can you do with it?

Beyond read/write/list — the nonobvious actions agents reach for:

Verify instead of trusting

file_ops(operation="get_file_hash", path="dist/app.zip")          # streamed sha256, never loads whole file
search_ops(operation="validate_config", path="config.yaml")        # json/yaml/toml/ini, precise error + line
search_ops(operation="run_linter", path="src/", fix=True)          # ruff check --fix, read-only unless fix=True

Understand a codebase in two calls

search_ops(operation="analyze_project", path=".")                  # type, markers, frameworks, top extensions
search_ops(operation="find_symbols", path="src", search_pattern="auth", recursive=True)  # defs, not grep noise
search_ops(operation="find_todos", path="src", recursive=True)     # TODO/FIXME/HACK/XXX/BUG with file:line

Move bulk safely

dir_ops(operation="copy_tree", path="D:/data", destination_path="E:/backup", dry_run=True)  # preview first
dir_ops(operation="copy_tree", path="D:/data", destination_path="E:/backup", engine="robocopy")  # fast lane, Windows
file_ops(operation="compress", path="D:/data")                     # zip without shelling out
file_ops(operation="append_file", path="app.log", content="line")  # locked append, no read-modify-write race

Undo and self-help

file_ops(operation="undo_edit", path="config.json")                # restore pre-edit .bak in one call
host_ops(operation="get_help", tool_name="search_ops")             # every tool documents itself; try it first

Deployment & Security

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

Tech Stack

Layer	Technology
Backend	Python 3.12, FastMCP 3.4+, FastAPI/Starlette, uvicorn, structlog, psutil, GitPython
Frontend	React 19, Vite 7, TailwindCSS 3, Lucide, Framer Motion, Zustand, Radix UI
Desktop	Tauri 2 (Rust), NSIS installer, embedded PyInstaller backend
Tooling	uv, just, ruff, Biome, pytest, pre-commit, Playwright

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:

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

Claude Desktop MCPB Package

One-line install (Claude Desktop):

iwr https://github.com/sandraschi/filesystem-mcp/releases/latest/download/install.ps1 -UseBasicParsing | iex

Or manually:

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. Start using 24 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 — moved

Git lives in git-github-mcp (gitops:git_core / gitops:github_ops). No git tools are registered here anymore.

Developer Tools — live as search_ops

find_todos, find_symbols, validate_json, analyze_project, run_linter (ruff-only), validate_config are live search_ops operations (read-only, tested). Still roadmap: analyze_dependencies, analyze_imports; check_file_sizes/detect_duplicates already exist as find_large_files/find_duplicate_files. Usage: search_ops(operation='find_todos', path='src', recursive=True) — not developer_tool(...).

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	path, output_format
check_file_sizes	Analyze file sizes and identify large files	path, recursive, max_results
detect_duplicates	Find duplicate files by content hash	path, recursive, max_results
find_symbols	Search for function/class definitions and usages	path, pattern, recursive
find_todos	Find TODO/FIXME comments in codebase	path, recursive, max_results
run_linter	Execute code linting (ruff, flake8, eslint)	path, fix, encoding
validate_config	Validate configuration files (JSON/YAML/TOML/INI)	path
validate_json	Parse and validate JSON files with structure analysis	path

Usage:

# Find all TODO comments (live)
todos = search_ops(operation='find_todos', path='src', recursive=True)

# Find function definitions (live)
symbols = search_ops(operation='find_symbols', path='src', search_pattern='auth', recursive=True)

# Validate JSON (live)
valid = search_ops(operation='validate_json', path='glama.json')

# Roadmap (not yet): analyze_dependencies, analyze_imports

Example Usage

from filesystem_mcp import app

# Get a list of available portmanteau tools
tools = app.list_tools()
print(f"Available portmanteau tools: {', '.join(tools.keys())}")

# Example: Filesystem operations
try:
    # Read a file
    result = tools["filesystem_operations"]("read_file", path="README.md")
    print(f"File content: {result['content'][:200]}...")

    # List directory contents
    result = tools["filesystem_operations"]("list_directory", path=".", recursive=False)
    print(f"Directory contents: {len(result['files'])} items")

    # Search for Python files
    result = tools["filesystem_operations"]("search_files", directory_path=".", pattern="*.py")
    print(f"Found {result['total_matches']} Python files")

except Exception as e:
    print(f"Filesystem error: {e}")

# Example: Docker operations
try:
    # List running containers
    result = tools["docker_operations"]("list_containers")
    print(f"Running containers: {len(result['containers'])}")

    # Get container details
    if result['containers']:
        container_id = result['containers'][0]['id']
        details = tools["docker_operations"]("get_container", container_id=container_id)
        print(f"Container {container_id}: {details['container']['status']}")

except Exception as e:
    print(f"Docker error: {e}")

# Example: Repository operations live in git-github-mcp (gitops), not here.
# See gitops:git_core (status, log, diff, commit, push, pull, clone, ...).

# Example: System operations
try:
    # Get system status
    result = tools["system_operations"]("get_system_status", include_processes=True)
    print(f"CPU usage: {result['cpu']['usage_percent']}%")
    print(f"Memory usage: {result['memory']['percent']}%")

    # Get help information
    result = tools["system_operations"]("get_help", category="filesystem")
    print(f"Available filesystem operations: {len(result.get('tools', {}))}")

except Exception as e:
    print(f"System error: {e}")

Development

Project Structure

filesystem-mcp/
 .github/                # GitHub workflows and templates
 docs/                   # Documentation files
 filesystem_mcp/         # Main package
    __init__.py         # Package initialization
    app.py              # FastAPI application setup
    config.py           # Configuration management
    models/             # Pydantic models
    tools/              # Tool implementations
       __init__.py     # Tool registration
       file_operations/  # File system tools
       docker_operations/ # Docker management tools
       repo_operations/  # Git repository tools
    utils/              # Utility functions
 tests/                  # Test suite
 .gitignore             # Git ignore rules
 LICENSE                # MIT License
 pyproject.toml         # Project configuration and dependencies
 README.md              # This file
 requirements-dev.txt    # Development dependencies

Running Tests

# Install test dependencies
pip install -r requirements-dev.txt

# Run all tests
pytest

# Run tests with coverage report
pytest --cov=filesystem_mcp --cov-report=term-missing

# Run specific test file
pytest tests/test_docker_operations.py -v

Code Style & Quality

This project enforces code quality using:

• Black - Code formatting
• isort - Import sorting
• mypy - Static type checking
• pylint - Code quality analysis

# Format code with Black
black .

# Sort imports with isort
isort .

# Type checking with mypy
mypy .

# Lint with pylint
pylint filesystem_mcp/

Building and Releasing

1. Update the version in pyproject.toml
2. Update CHANGELOG.md
3. Commit changes with a message like "Bump version to x.y.z"
4. Create a git tag: git tag vx.y.z
5. Push the tag: git push origin vx.y.z
6. GitHub Actions will automatically build and publish the package to PyPI

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on how to submit pull requests, report issues, or suggest new features.

🛡️ Industrial Quality Stack

This project adheres to SOTA 14.1 industrial standards for high-fidelity agentic orchestration:

• Python (Core): Ruff for linting and formatting. Zero-tolerance for print statements in core handlers (T201).
• Webapp (UI): Biome for sub-millisecond linting. Strict noConsoleLog enforcement.
• Protocol Compliance: Hardened stdout/stderr isolation to ensure crash-resistant JSON-RPC communication.
• Automation: Justfile recipes for all fleet operations (just lint, just fix, just dev).
• Security: Automated audits via bandit and safety.

License

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

Changelog

See CHANGELOG.md for a history of changes to this project.

Topics

filesystem mcp-server fastmcp file-operations docker system-monitoring python mcp model-context-protocol portmanteau concurrency-safe

Webapp Dashboard

This MCP server includes a free, premium web interface for monitoring and control. By default, the web dashboard runs on port 10742. (Assigned ports: 10742 (Backend (was 13000)), 10743 (Frontend (was 13001)))

To start the webapp:

1. Navigate to the webapp (or web, frontend) directory.
2. Run start.bat (Windows) or ./start.ps1 (PowerShell).
3. Open http://localhost:10742 in your browser.