Filesystem

You can run the Filesystem MCP Server over HTTP Streaming to manage and access your project filesystem remotely. It preserves all filesystem operations while adding remote accessibility, concurrent sessions, and browser-friendly clients with OAuth 2.1 PKCE authentication.

How to use

Use an MCP client to connect to the server over HTTP Streaming. You can initialize credentials, start the server for a directory you want to manage, and then interact with the filesystem through MCP messages. The server supports initializing sessions, performing read/write operations, directory management, file search, and metadata queries. Authentication is handled via OAuth 2.1 with PKCE, so you’ll obtain an access token for subsequent requests and can manage access with tokens that are rotated on refresh.

How to install

Prerequisites you need installed first: Node.js and npm on your system.

Install the MCP Filesystem Server globally so you can run the mcpfs CLI from anywhere.

npm install -g mcpfs

For local development and testing, install dependencies and build the project locally.

npm install
npm run build

Initialize credentials to create a .env file with random values, then start the server pointing to the directory you want to manage.

mcpfs --init
mcpfs /path/to/your/project

Configuration and usage notes

Default behavior serves the current working directory if it is considered safe. It will not auto-serve root, home, or system directories unless you explicitly specify them on the command line. You can also enable dynamic directory access control through Roots so MCP clients can adjust allowed directories at runtime.

Security

The server uses OAuth 2.1 with PKCE for authorization, binding tokens to the resource server, and rotating tokens on refresh. Only directories specified at startup or provided via Roots are accessible. Symlinks are resolved to prevent directory escape attacks.

API and endpoints overview

The server exposes OAuth 2.1 endpoints for dynamic client registration and token exchange, plus an MCP endpoint for sending and receiving messages over HTTP Streaming. You authenticate with Bearer tokens when performing MCP operations.

Troubleshooting and tips

If you encounter connection issues, ensure your OAuth client is correctly configured (client ID and secret), verify your token is valid, and check that the server port is accessible from your client. Remember that tunnel-based publishing (to expose localhost) requires a public URL and proper routing to your MCP endpoint.

Example workflow (summary)

1) Run: mcpfs --init
2) Start server: mcpfs /path/to/your/project
3) Obtain access token via the OAuth flow (PKCE or client credentials)
4) Use MCP messages to read/write files, manage directories, and query metadata

Available tools

read_text_file

Read complete contents of a file as text. Inputs: path, head, tail.

read_media_file

Read an image or audio file as base64. Input: path.

read_multiple_files

Read multiple files simultaneously. Input: paths.

write_file

Create new file or overwrite existing. Inputs: path, content.

edit_file

Make selective edits with pattern matching. Inputs: path, edits, dryRun.

create_directory

Create new directory or ensure it exists. Input: path.

list_directory

List directory contents with [FILE] or [DIR] prefixes. Input: path.

list_directory_with_sizes

List directory with file sizes. Inputs: path, sortBy.

move_file

Move or rename files and directories. Inputs: source, destination.

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.

list_allowed_directories

List all accessible directories. No input.