Filesystem

You are provided with a robust MCP server that exposes filesystem operations to AI agents. It supports reading, writing, updating, listing, and managing files and directories, with strong security, validation, and the option to communicate via STDIO or HTTP transport. This guide walks you through how to use the server, how to install and run it, and how to configure it for secure production use.

How to use

You will run the MCP server and connect an MCP client to access its filesystem tools. Start the server in STDIO mode for direct process communication or use HTTP for network-based access. When connected, you can set a default filesystem path for the session, then perform operations such as reading, writing, updating, listing, moving, copying, or deleting files and directories. Security is enforced through path sanitization and, for HTTP transport, JWT authentication.

How to install

# Prerequisites
- Node.js (and npm) installed
- Optional: npm@latest for best compatibility

# 1) Clone the repository
git clone https://github.com/cyanheads/filesystem-mcp-server.git
cd filesystem-mcp-server

# 2) Install dependencies
npm install

# 3) Build the project
npm run build

# 4) Start the server (STDIO example considered running the built binary via node)
node dist/index.js

# Alternatively, start via npm script if provided
npm start
```} ,{

Configuration and security notes

Configure the server with environment variables to tailor behavior and security. Core settings cover logging, environment, and transport mode. Transport settings enable either STDIO or HTTP. If you choose HTTP, you will enable JWT authentication and host/port control. A critical security feature is restricting filesystem access to a base directory you specify using FS_BASE_DIRECTORY; all operations will be resolved within this root and its subdirectories.

Key environment variables you will typically configure include MCP_LOG_LEVEL, LOGS_DIR, NODE_ENV, MCP_TRANSPORT_TYPE, MCP_HTTP_PORT, MCP_HTTP_HOST, MCP_ALLOWED_ORIGINS, MCP_AUTH_SECRET_KEY, and FS_BASE_DIRECTORY. For HTTP transport, provide a secure secret key (minimum 32 characters) to enable JWT authentication. Ensure that FS_BASE_DIRECTORY is set to a safe directory (absolute path preferred) to prevent access outside the intended area.

Notes on using separate transport modes

STDIO transport is ideal when running as a child process and communicating directly with your host application. HTTP transport opens RESTful endpoints with optional streaming via Server-Sent Events (SSE) and requires JWT authentication if enabled. Pick the transport method that best fits your deployment scenario and security posture.

Available tools

set_filesystem_default

Sets a default absolute path for the current session so relative paths are resolved against it. The default resets on server restart.

read_file

Reads the entire content of a file as UTF-8 text. Accepts relative (resolved against the default) or absolute paths.

write_file

Writes content to a file, creating parent directories if needed. Overwrites existing content.

update_file

Performs targeted search-and-replace within a file using blocks of search/replace. Supports plain text or regex and can replace all occurrences.

list_files

Lists files and directories within a path, with optional recursive listing and entry limits. Returns a formatted tree structure.

delete_file

Deletes a specified file. Relative or absolute paths are accepted.

delete_directory

Deletes a directory. Use recursive to remove non-empty directories.

create_directory

Creates a directory, creating any necessary parent directories by default.

move_path

Moves or renames a file or directory from a source path to a destination path.

copy_path

Copies a file or directory from a source path to a destination path, recursively for directories by default.