StartFilesystemMCP

A sandboxed filesystem MCP server written in Python (FastMCP). It gives an AI agent safe file, search, git-lite and handoff tools inside one workspace folder, and doubles as shared memory between sessions through a Handoff Protocol (PROJECT_STATE, PLAN_LOG, CHECKPOINTS, DECISIONS).

Course project: Midterms Pt 1 - Build Your Own (Model Context Protocol).

Features

• Sandboxed workspace root. Every path is resolved against the workspace; ..\ traversal, absolute paths and prefix tricks (MCP-activity-evil) are rejected.
• 14 tools: file ops, search, git-lite and handoff tools (table below).
• Two transports: stdio (Claude Desktop) and streamable HTTP.
• HTTPS through a Cloudflare tunnel, kept alive by Windows services (NSSM).
• Token auth for the HTTP endpoint (MCP_TOKEN).
• Version locking (if_version) so one session cannot overwrite another’s changes.
• Handoff Protocol so a new session can resume work from the files alone.

Requirements

• Windows 10/11
• Python 3.10+ with the mcp package: pip install mcp
• Git for Windows (for the git-lite tools)
• Claude Desktop (MCP client)
• For the HTTPS part: cloudflared and NSSM (winget install Cloudflare.cloudflared and winget install NSSM.NSSM)

Setup

1. Clone the repo into the workspace folder, or copy mcp_server.py there.
2. Set WORKSPACE_ROOT at the top of mcp_server.py to your folder (default: C:\Users\Colee\MCP-activity).
3. Make sure the four handoff files exist in that folder.

Run over stdio (Claude Desktop)

Add this to claude_desktop_config.json and restart Claude Desktop:

{
  "mcpServers": {
    "filesystem": {
      "command": "C:\\PYTHON314\\PYTHON.EXE",
      "args": ["C:\\Users\\Colee\\MCP-activity\\mcp_server.py"]
    }
  }
}

Run over HTTP

$env:MCP_TOKEN = -join ((48..57)+(97..122) | Get-Random -Count 24 | % {[char]$_})
$env:MCP_TOKEN                      # copy this value
python mcp_server.py --http         # serves http://127.0.0.1:8000/mcp

Without a token the endpoint is open to anyone who has the URL, so always set one.

Expose it over HTTPS (Cloudflare quick tunnel)

cloudflared tunnel --url http://127.0.0.1:8000

The command prints an address like https://.trycloudflare.com. In Claude Desktop add a custom connector named filesystem-http with the URL:

https://.trycloudflare.com/mcp?token=

Quick tunnel addresses change every time the tunnel restarts.

Keep it alive (NSSM, run in an Administrator PowerShell)

nssm install McpServer "C:\PYTHON314\PYTHON.EXE" "C:\Users\Colee\MCP-activity\mcp_server.py --http"
nssm set McpServer AppDirectory "C:\Users\Colee\MCP-activity"
nssm set McpServer AppEnvironmentExtra "MCP_TOKEN=$env:MCP_TOKEN"
nssm set McpServer Start SERVICE_AUTO_START
nssm start McpServer

$cf = (Get-Command cloudflared).Source