# Filesystem Mcp

> FastMCP 3.2.0+ server plus webapp for comprehensive file system operations, Git repository management, Docker container control, and developer tools for Claude Desktop integration.

- **Type:** MCP server
- **Install:** `agentstack add mcp-sandraschi-filesystem-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sandraschi](https://agentstack.voostack.com/s/sandraschi)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [sandraschi](https://github.com/sandraschi)
- **Source:** https://github.com/sandraschi/filesystem-mcp

## Install

```sh
agentstack add mcp-sandraschi-filesystem-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```powershell
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](https://docs.astral.sh/uv/) installed (RECOMMENDED)
- Python 3.12+

###  Quick Start
Run immediately via `uvx`:
```bash
uvx filesystem-mcp
```

###  Claude Desktop Integration
Add to your `claude_desktop_config.json`:
```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:**

```bash
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](https://github.com/sandr/filesystem-mcp/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](https://docs.astral.sh/uv/) installed (RECOMMENDED)
- Python 3.12+

###  Quick Start
Run immediately via `uvx`:
```bash
uvx filesystem-mcp
```

###  Claude Desktop Integration
Add to your `claude_desktop_config.json`:
```json
"mcpServers": {
  "filesystem-mcp": {
    "command": "uv",
    "args": ["--directory", "D:/Dev/repos/filesystem-mcp", "run", "filesystem-mcp"]
  }
}
```
##  Installation

### Prerequisites
- [uv](https://docs.astral.sh/uv/) installed (RECOMMENDED)
- Python 3.12+

###  Quick Start
Run immediately via `uvx`:
```bash
uvx filesystem-mcp
```

###  Claude Desktop Integration
Add to your `claude_desktop_config.json`:
```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:

```bash
# 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:

```python
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:
```bash
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:**
```bash
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:**
```json
{
  "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:**
```json
{
  "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](https://docs.astral.sh/uv/) installed (RECOMMENDED)
- Python 3.12+

###  Quick Start
Run immediately via `uvx`:
```bash
uvx filesystem-mcp
```

###  Claude Desktop Integration
Add to your `claude_desktop_config.json`:
```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

```python
# 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:

```python
# 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:

```python
# 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

```bash
# 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.

```python
# 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`

```python
# 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`

```python
# 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](https://github.com/sandraschi)
- **Source:** [sandraschi/filesystem-mcp](https://github.com/sandraschi/filesystem-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sandraschi-filesystem-mcp
- Seller: https://agentstack.voostack.com/s/sandraschi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.