⚡ FastMCP Filesystem Server & AI Assistant

A high-performance, sandboxed filesystem manager built on the Model Context Protocol (MCP) with FastMCP, featuring a reactive Streamlit UI and OpenAI function calling.

Features • Claude Desktop Setup • Architecture • Tools • Quickstart

🛡️ Security & M8ven Trust Verification

This MCP server is listed and independently verified on the M8ven Trust Index:

• 🔒 Sandboxed Path Validation: Restricts all file mutations within the isolated workspace with path traversal (../) prevention.

• ⚡ Model Context Protocol (MCP): Native stdio/SSE tools compatible with Claude Desktop and FastMCP runtime.

• 📋 Trust Inspection: Check the latest security audit and independent review on M8ven.

Related MCP server: ai-distiller-mcp

🎯 What is This?

An enterprise-ready AI file manager built with Anthropic's Model Context Protocol (MCP) and FastMCP. It bridges LLM reasoning directly to local filesystem operations inside a hardened, sandboxed workspace with complete path-traversal prevention.

• 🤖 Autonomous AI Tool Calling: OpenAI GPT-4o function-calling automatically selects the optimal file tools based on natural language prompts.

• 🔒 Sandboxed File Operations: Strict path validation prevents any access outside the designated workspace/ boundary.

• 🎨 Full-Stack Web Interface: Modern 3-tab Streamlit dashboard (Agent Chat, Live File Tree Explorer, Direct Quick-Action Tools).

• ⚡ Production FastMCP Engine: SSE (Server-Sent Events) and stdio transport with asynchronous I/O and zero memory leaks.

🔌 Connect to Claude Desktop (in 10s)

You can connect this MCP server directly to Anthropic Claude Desktop so Claude can inspect, create, read, and organize your files locally.

Add the following to your claude_desktop_config.json:

• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

{
  "mcpServers": {
    "filesystem-fastmcp": {
      "command": "python",
      "args": [
        "-m",
        "server.filesystem_mcp_server"
      ],
      "cwd": "C:/path/to/filesystem-mcp-with-FastMCP-server"
    }
  }
}

Restart Claude Desktop, and you will see the hammer icon 🔨 with all 8 filesystem tools ready to use!

🏗️ Architecture

flowchart TD
    User([User Prompt]) --> UI[Streamlit Host App / Claude Desktop]
    UI --> LLM[LLM Agent / GPT-4o / Claude 3.5 Sonnet]
    LLM -->|Function Calling / MCP Protocol| FastMCP[FastMCP Server]
    
    subgraph Sandbox [Security Boundary: workspace/]
        FastMCP --> Validator[Path Traversal & Permission Guard]
        Validator --> Read[File Read & Search Engine]
        Validator --> Write[Atomic Write & Backup Engine]
        Validator --> Meta[Directory Tree & Metadata Inspector]
    end
    
    Validator --> Log[Structured Audit Logger]

🛠️ 8 Available MCP Tools

🚀 Quickstart

1. Clone & Setup Environment

git clone https://github.com/Bosaj/filesystem-mcp-with-FastMCP-server.git
cd filesystem-mcp-with-FastMCP-server

python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

pip install -r requirements.txt

2. Configure Environment Variables

cp .env.example .env
# Edit .env and set your OPENAI_API_KEY

3. Run the Standalone FastMCP Server

python -m server.filesystem_mcp_server

4. Run the Streamlit Interactive Web Interface

streamlit run host/app.py

🧪 Testing & Verification

Run the automated test suite and lint checks:

pytest tests/ -v --cov=server --cov-report=term-missing
flake8 server/ host/
black --check server/ host/

👥 Contributors & Authors

• Oussama EL HADJI (@Bosaj) — Core Architecture, FastMCP server implementation, and CI/CD pipelines.

• chakorabdellatif — Collaborative development and testing.

• yassinebenacha — Frontend dashboard review.

📄 License

This project is licensed under the MIT License.