Filesystem MCP Server (HTTP Streaming)

An HTTP streaming port of the official MCP Filesystem Server by Anthropic.

About This Port

This is a port of @modelcontextprotocol/server-filesystem that replaces the stdio transport with HTTP Streaming (Streamable HTTP transport).

Why HTTP Streaming?

The original MCP filesystem server uses stdio transport, which works well for local CLI integrations but has limitations:

• Requires spawning a subprocess for each connection
• Not suitable for remote/networked deployments
• Can't be accessed by web-based MCP clients

This port uses HTTP Streaming, enabling:

• Remote access - Connect over HTTP from anywhere
• Multiple concurrent sessions - Handle many clients simultaneously
• Web client compatibility - Works with browser-based MCP clients
• Standalone deployment - Run as a service without subprocess management

All filesystem functionality from the original is preserved.

---

Features

• Read/write files
• Create/list/delete directories
• Move files/directories
• Search files
• Get file metadata
• Dynamic directory access control via Roots
• OAuth 2.1 authentication with PKCE support
• ChatGPT integration via MCP connectors

Installation

npm install -g mcpfs

Or for local development:

npm install
npm run build

Quick Start

# Initialize credentials (creates .env with random values)
mcpfs --init

# Start the server
mcpfs /path/to/your/project

Using with ChatGPT

ChatGPT requires a publicly accessible HTTPS URL. Use Cloudflare Tunnel (free) to expose your local server:

Step 1: Install Cloudflare Tunnel

# Linux
curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared
chmod +x cloudflared
sudo mv cloudflared /usr/local/bin/

# Mac
brew install cloudflared

# Windows - download from:
# https://github.com/cloudflare/cloudflared/releases

Step 2: Start mcpfs

mcpfs --init  # First time only - creates credentials
mcpfs /path/to/your/project

Step 3: Start the Tunnel

In a separate terminal:

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

You'll get a URL like https://random-words.trycloudflare.com

Step 4: Connect in ChatGPT

1. Go to ChatGPT → Settings → Connectors → Create
2. Name: mcpfs (or any name you prefer)
3. URL: https://random-words.trycloudflare.com/mcp (use your tunnel URL + /mcp)
4. Authentication: OAuth
5. Client ID: Copy from your .env file
6. Client Secret: Copy from your .env file
7. Click Create

ChatGPT will redirect you to authorize. Once complete, you can use filesystem tools in ChatGPT!

Note on Tunnel URLs

Quick tunnels generate a new URL each time. For a permanent URL:

• Create a free Cloudflare account
• Set up a named tunnel with your own domain

---

Usage

Default Directory Behavior

When no directories are specified, the server will serve the current working directory if it's considered safe. The server will refuse to auto-serve:

• Root directory (/)
• Home directory (~)
• System directories (/usr, /etc, /var, /System, etc.)

To serve these directories, you must specify them explicitly as command-line arguments.

Command Line Options

Option	Description
--init	Generate random credentials and save to .env
--force	Used with --init to overwrite existing .env

Environment Variables

CLIENT_ID=myid CLIENT_SECRET=mysecret mcpfs /path/to/dir

# With custom port
PORT=8080 CLIENT_ID=myid CLIENT_SECRET=mysecret mcpfs /path/to/dir

Variable	Required	Default	Description
CLIENT_ID	Yes	-	OAuth client ID
CLIENT_SECRET	Yes	-	OAuth client secret
PORT	No	24024	Server port

---

HTTP Endpoints

OAuth 2.1 Discovery (RFC 9728, RFC 8414)

Method	Path	Description
GET	/.well-known/oauth-protected-resource	Protected resource metadata
GET	/.well-known/oauth-authorization-server	Authorization server metadata

OAuth 2.1 Endpoints

Method	Path	Description
POST	/register	Dynamic client registration (RFC 7591)
GET	/authorize	Authorization endpoint with PKCE
POST	/token	Token endpoint

MCP Endpoints

Method	Path	Auth	Description
POST	/mcp	Bearer	Send MCP messages (initialize, tool calls, etc.)
GET	/mcp	Bearer	SSE stream for server-to-client notifications
DELETE	/mcp	Bearer	Terminate session

---

Authentication

This server supports OAuth 2.1 with multiple authentication flows:

Authorization Code Flow with PKCE (Recommended)

Used by ChatGPT and other MCP clients. The flow is:

1. Client discovers OAuth endpoints via /.well-known/oauth-authorization-server
2. Client registers dynamically via /register (or uses static credentials)
3. Client redirects to /authorize with PKCE challenge
4. Server redirects back with authorization code
5. Client exchanges code for tokens at /token

Client Credentials Flow (Machine-to-Machine)

For direct API access without user interaction:

curl -X POST http://localhost:24024/token \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"

Response:

{
  "access_token": "abc123...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Using the Token

curl -X POST http://localhost:24024/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "my-client", "version": "1.0.0" }
    }
  }'

---

Directory Access Control

The server uses a flexible directory access control system.

Method 1: Command-line Arguments

mcpfs /path/to/dir1 /path/to/dir2

Method 2: MCP Roots (Recommended)

MCP clients that support Roots can dynamically update the allowed directories.

How It Works

1. Server Startup - Server starts with directories from command-line arguments
2. Client Connection - Client connects and sends initialize request
3. Roots Protocol - If client supports roots, server uses client's roots
4. Fallback - If client doesn't support roots, server uses command-line directories
5. Access Control - All filesystem operations are restricted to allowed directories

---

API

Tools

• read_text_file

  • Read complete contents of a file as text
  • Inputs:
    • path (string)
    • head (number, optional): First N lines
    • tail (number, optional): Last N lines

• read_media_file

  • Read an image or audio file as base64
  • Input: path (string)

• read_multiple_files

  • Read multiple files simultaneously
  • Input: paths (string[])

• write_file

  • Create new file or overwrite existing
  • Inputs: path (string), content (string)

• edit_file

  • Make selective edits with pattern matching
  • Inputs: path, edits (array of oldText/newText), dryRun (boolean)

• create_directory

  • Create new directory or ensure it exists
  • Input: path (string)

• list_directory

  • List directory contents with [FILE] or [DIR] prefixes
  • Input: path (string)

• list_directory_with_sizes

  • List directory with file sizes
  • Inputs: path (string), sortBy ("name" | "size")

• move_file

  • Move or rename files and directories
  • Inputs: source (string), destination (string)

• search_files

  • Recursively search for files matching patterns
  • Inputs: path, pattern, excludePatterns

• directory_tree

  • Get recursive JSON tree structure
  • Inputs: path, excludePatterns

• get_file_info

  • Get detailed file/directory metadata
  • Input: path (string)

• list_allowed_directories

  • List all accessible directories
  • No input required

Tool Annotations

Tool	readOnlyHint	idempotentHint	destructiveHint
read_text_file	true	–	–
read_media_file	true	–	–
read_multiple_files	true	–	–
list_directory	true	–	–
list_directory_with_sizes	true	–	–
directory_tree	true	–	–
search_files	true	–	–
get_file_info	true	–	–
list_allowed_directories	true	–	–
create_directory	false	true	false
write_file	false	true	true
edit_file	false	false	true
move_file	false	false	false

---

Security

• OAuth 2.1 authentication with PKCE for authorization code flow
• Token audience validation - tokens are bound to the resource server
• Refresh token rotation - tokens are rotated on each refresh (OAuth 2.1 requirement)
• Only directories specified at startup (or via MCP Roots) are accessible
• Symlinks are resolved to prevent directory escape attacks

License

MIT License. See LICENSE file for details.

Credits

Based on the MCP Filesystem Server by Anthropic, PBC.