Remote Project File-System MCP for Claude Web

A production-grade, secure Model Context Protocol (MCP) server built with Python and FastMCP. It allows Claude Web (and Claude in Chrome) to securely inspect, search, and modify the files of a local project workspace being developed alongside Antigravity IDE.

1. Architecture Overview

How Antigravity and Claude Work Together

Both Antigravity IDE and the Project Files MCP server operate on the same local project directory on your machine (e.g. C:\Projects\NeuroScan).

                       My Windows PC
  ┌─────────────────────────────────────────────────────────┐
  │                                                         │
  │   Antigravity IDE                                       │
  │         │                                               │
  │         ▼                                               │
  │   Local Project Files  ◄───  Project Files MCP Server   │
  │   (e.g., C:\Projects\NeuroScan)         │               │
  └─────────────────────────────────────────┼───────────────┘
                                            │
                                 Secure HTTPS / SSE Tunnel
                                 (FastMCP / Cloudflare / ngrok)
                                            │
                                            ▼
                                       Claude Web
                                (Custom MCP Connector)

1. Antigravity IDE has your project directory open and active.

2. Project Files MCP server is configured with PROJECT_ROOT pointing to that same directory.

3. Claude Web calls the MCP tools to inspect file trees, search code, read functions, and make targeted file modifications.

4. Changes made by Claude immediately reflect in Antigravity and your local file system.

Important Architecture Constraint: Local Files vs. FastMCP Cloud

Option A: Local FastMCP Server + Secure HTTPS Tunnel (Recommended for Local Projects)

1. Run the MCP server locally on your Windows machine pointing PROJECT_ROOT to your project directory.

2. Expose the server using FastMCP SSE / HTTP via a lightweight tunnel (e.g., Cloudflare Tunnel cloudflared, ngrok, or FastMCP local tunnel).

3. Provide the resulting HTTPS URL to Claude Web as a Custom MCP Connector.

Option B: FastMCP Cloud Direct Deployment (For Cloud/Container Repositories)

1. Deploy this repository to FastMCP Cloud.

2. Set PROJECT_ROOT to the mounted repository path inside the cloud environment.

3. Connect the FastMCP Cloud endpoint directly to Claude Web.

Related MCP server: ai-distiller-mcp

2. Key Features

• Strict Sandbox Security: Every path is normalized, verified against path traversal (../), symlink escapes, and absolute path injections. Operations are strictly restricted to PROJECT_ROOT.

• Sensitive File Protection: Automatic denylist blocks access to .env, private keys (id_rsa, *.pem, *.key), and secrets (while permitting safe templates like .env.example).

• Targeted Code Search: Fast recursive search with surrounding context lines and line numbers. Automatically ignores build directories (.git, node_modules, .venv, dist, build, etc.).

• Atomic File Writing: Modifications use temporary files and atomic replacement (os.replace) to prevent file corruption.

• Safe Targeted Edits: edit_file enforces unambiguous text matching and prevents accidental multi-location edits unless replace_all=True.

• Large & Binary File Protection: Binary files are safely detected and directed to metadata inspection without terminal corruption. Large files enforce chunked reading (start_line / end_line).

• Server Audit Logging: Server-side logs record actions, paths, and status without leaking file contents or secrets.

3. MCP Tools Reference

The server exposes 17 specialized tools with detailed parameter schemas and safety indicators:

Read & Inspection Tools (Safe / Read-Only)

Modification Tools (Marked [MODIFIES PROJECT FILES] / [DESTRUCTIVE OPERATION])

Read-Only MCP Resources

• project://tree - Fast ASCII tree view of the active workspace.

• project://statistics - High-level project summary statistics (JSON).

• project://README - Content of the project's root README.md file.

4. Installation & Local Setup

1. Prerequisites

• Python 3.10+ (or Python 3.11+)

• Windows, macOS, or Linux

2. Clone and Setup Virtual Environment

# Clone the repository
git clone https://github.com/your-username/project-files-mcp.git
cd project-files-mcp

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows PowerShell:
.venv\Scripts\Activate.ps1
# On Windows Command Prompt:
.venv\Scripts\activate.bat
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

5. Configuration

Configure the server via environment variables or a .env file:

cp .env.example .env

Example for Antigravity Workspace:

PROJECT_ROOT=C:\Projects\NeuroScan
LOG_LEVEL=INFO

6. Running and Testing Locally

Run Unit Tests

Run the comprehensive pytest suite (43 automated tests covering security, filesystem, search, and MCP tools):

.venv\Scripts\pytest.exe -v

Run End-to-End Verification

Execute the simulated Claude workflow test:

.venv\Scripts\python.exe scripts/e2e_verification.py

Start the FastMCP Server Locally

# Run FastMCP in standard stdio mode
.venv\Scripts\python.exe src/server.py

# Or run with FastMCP CLI inspector for local interactive browser testing:
fastmcp dev src/server.py

7. Connecting to Claude Web

Step 1: Start FastMCP HTTP/SSE Server with Local Project Files

To allow Claude Web to reach your local server, run FastMCP in HTTP/SSE mode on port 8000:

# Set your target project root
$env:PROJECT_ROOT = "C:\Projects\NeuroScan"

# Start the FastMCP HTTP server
fastmcp run src/server.py --transport sse --port 8000

Step 2: Expose via a Secure HTTPS Tunnel

In a second terminal, create a secure HTTPS tunnel to port 8000:

Option 1: Using Cloudflare Tunnel (Free, no account required):

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

Option 2: Using ngrok:

ngrok http 8000

You will receive an HTTPS URL, for example:

https://my-project-mcp.trycloudflare.com/sse

Step 3: Add Custom Connector in Claude Web

1. Open Claude.ai in your browser.

2. Go to Settings > Integrations / Connectors (or Add Custom MCP Server).

3. Enter:

   • Name: Project Files MCP

   • Endpoint URL: https://my-project-mcp.trycloudflare.com/sse

4. Click Save and verify the green connected indicator.

Step 4: Use in Project Conversations

1. Open your project conversation in Claude Web.

2. Ensure the Project Files MCP tool is enabled.

3. Ask Claude to inspect and work with your project files!

8. Claude Web Workflow Guidance & Example Prompts

The MCP is designed so Claude follows an efficient, targeted workflow:

Understand Request  ──►  get_project_tree()  ──►  search_code()  ──►  read_file() (targeted)
                                                                            │
Report to User      ◄──  read_file() (verify) ◄──  edit_file()   ◄─────────┘

Example Prompts for Claude:

1. Inspecting Architecture

"Inspect my project structure and explain the key components in the src/ directory."

2. Locating Implementation

"Search the codebase for authentication and token validation functions."

3. Reading Specific Logic

"Read src/auth/service.py around the login function and explain how sessions are handled."

4. Safe Targeted Refactoring

"In src/config.py, change TOKEN_EXPIRY_MINUTES = 30 to TOKEN_EXPIRY_MINUTES = 60 and verify the change."

5. Creating New Modules

"Create a new utility file at src/utils/formatting.py with helper functions for formatting timestamps."

6. Safe Deletions & Renaming

"Rename src/old_service.py to src/legacy_service.py."

9. Security Model

• Filesystem Isolation: All paths are resolved strictly against settings.project_root.

• Traversal Prevention: Relative paths containing .. or leading slashes that resolve outside the project root are rejected with a SecurityError.

• Sensitive Files Denylist: Proactively blocks reading .env, .env.local, .env.production, id_rsa, id_ed25519, *.pem, *.key, credentials.json, and secrets.json. Safe templates (.env.example) are allowed.

• Root Protection: The root workspace directory itself can never be deleted or replaced.

• No Arbitrary Code Execution: The server exposes strictly filesystem and search operations. There is no run_command or shell execution tool, preventing remote command execution risks.

• Atomic Operations: All file writes and edits are performed using temporary files with atomic replacement to prevent file corruption during writes.

10. Limitations

• No Remote Shell: Arbitrary terminal commands (e.g. npm install, python script.py) cannot be executed through this MCP.

• Antigravity State: The MCP interacts directly with the filesystem on disk. It does not control Antigravity IDE UI or memory state directly; Antigravity will automatically detect and reload the modified files from disk.

• Binary Content: Binary files (images, audio, compiled binaries) cannot be read as text to avoid payload corruption; use get_file_metadata or inspect_project_file instead.

• Direct Cloud to Local Limitation: A cloud-hosted MCP container cannot reach a local Windows filesystem without a tunnel (like Cloudflare Tunnel or ngrok) or bridge.

11. Project Layout

project-files-mcp/
│
├── src/
│   ├── __init__.py           # Package init
│   ├── config.py             # Configuration & environment variables
│   ├── exceptions.py         # Custom typed exceptions
│   ├── security.py           # Path sandboxing, traversal & sensitive file checks
│   ├── models.py             # Pydantic structured output models
│   ├── filesystem.py         # Core filesystem operations (atomic write, edit, tree, metadata)
│   ├── search.py             # File & code search with context windows
│   ├── audit.py              # Safe server-side audit logging
│   └── server.py             # FastMCP server instance, tools, and resources
│
├── tests/
│   ├── __init__.py
│   ├── conftest.py           # Test fixtures & mock project workspace
│   ├── test_security.py      # Traversal, symlink, absolute path & secret tests
│   ├── test_filesystem.py    # Read, partial slice, write, edit, rename, move, delete tests
│   ├── test_search.py        # Code search, file search & ignore filtering tests
│   └── test_server.py        # FastMCP tool interface & resource tests
│
├── scripts/
│   └── e2e_verification.py   # Complete end-to-end verification script
│
├── .env.example              # Sample environment configuration
├── .gitignore                # Git ignore rules
├── pyproject.toml            # Packaging configuration
├── requirements.txt          # Python dependencies
├── fastmcp.json              # FastMCP Cloud deployment configuration
└── README.md                 # Complete documentation

12. License

MIT License. Free for open-source and commercial use.