FastMCP Filesystem Server

A secure, feature-rich filesystem MCP (Model Context Protocol) server built with FastMCP. Enables AI assistants like Claude to safely read, write, search, and manage files on your local machine with configurable path restrictions.

Features

• 🔒 Security First: Path sandboxing prevents unauthorized directory access
• 📁 Complete Operations: List, read, write, create, delete, move, copy files and directories
• 🔍 Smart Search: Glob pattern matching with optional content regex search
• 📊 Metadata: File hashes (MD5), MIME types, permissions, timestamps
• 🚀 FastMCP Powered: Clean decorator-based API, async support, multiple transports
• 🛠️ Production Ready: Error handling, logging, size limits, encoding detection

Quick Start

Installation

# Clone repository
git clone https://github.com/newbieking/fastmcp-filesystem-server.git
cd fastmcp-filesystem-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install fastmcp

Usage

Standalone Mode

# Allow access to specific directories only (recommended)
python filesystem_server.py /home/user/Documents /home/user/Projects

# Development mode (no restrictions - use with caution)
python filesystem_server.py

With Claude Desktop

Add to your Claude Desktop configuration:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": [
        "/absolute/path/to/filesystem_server.py",
        "/Users/yourname/Documents",
        "/Users/yourname/Projects"
      ]
    }
  }
}

Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "filesystem": {
      "command": "python",
      "args": [
        "C:\\path\\to\\filesystem_server.py",
        "C:\\Users\\yourname\\Documents"
      ]
    }
  }
}

Available Tools

Examples

List Directory

{
  "path": "/home/user/Projects"
}

Read Large File (Chunked)

{
  "path": "/var/log/syslog",
  "offset": 0,
  "limit": 10240
}

Search Python Files Containing "TODO"

{
  "path": "/home/user/Projects",
  "pattern": "*.py",
  "content_pattern": "TODO|FIXME",
  "max_depth": 3
}

Write Configuration File

{
  "path": "/home/user/.config/app/settings.json",
  "content": "{\"theme\": \"dark\", \"version\": \"1.0\"}"
}

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Claude/AI     │◄───►│  MCP Protocol    │◄───►│  FastMCP Server │
│   Assistant     │     │  (stdio/SSE)     │     │                 │
└─────────────────┘     └──────────────────┘     └────────┬────────┘
                                                          │
                              ┌───────────────────────────┼───────────┐
                              ▼                           ▼           ▼
                        ┌──────────┐               ┌────────────┐ ┌────────┐
                        │ Path     │               │ File Ops   │ │ Search │
                        │ Validator│               │ (read/write)│ │ Engine │
                        └──────────┘               └────────────┘ └────────┘

Security Considerations

⚠️ Important: This server grants AI assistants direct filesystem access.

1. Always use path restrictions in production:

   python filesystem_server.py /safe/path/only
   

2. Never run with sudo/root permissions

3. Audit sensitive directories: Avoid exposing .ssh/, .env files, or financial data

4. Review AI actions: Claude will ask permission before destructive operations (delete/overwrite)

Development

Testing

# Run tests
pytest tests/

# Test with MCP Inspector
npx @modelcontextprotocol/inspector --config mcp-config.json --server fs-server

Project Structure

.
├── mcp-config.json        # mcp config file for mcp client
├── README.md              # This file
└── fast_mcp_server/
    └── filesystem_server.py  # Main MCP server implementation

Requirements

• Python 3.10+
• fastmcp>=1.0.0
• mcp>=1.0.0

License

MIT License - see LICENSE file.

Related

• Model Context Protocol
• FastMCP
• Claude Desktop

Built with FastMCP | Secure by Design | AI-Ready