Filesystem MCP Server

Name: Filesystem MCP Server
Author: cyanheads

@cyanheads

About Filesystem MCP Server

A Model Context Protocol (MCP) server for platform-agnostic file capabilities, including advanced search/replace and directory tree traversal

#ai #filesystem #mcp #llm-agents #model-context-protocol #mcp-server #modelcontextprotocol

Basic information

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "filesystem-mcp-server": {
      "command": "node",
      "args": [
        "dist/index.js"
      ]
    }
  }
}

Tools

Sets a default absolute path for the current session. Relative paths used in subsequent tool calls will be resolved against this default. Resets on server restart.

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

Writes content to a specified file. Creates the file (and necessary parent directories) if it doesn't exist, or overwrites it if it does. Accepts relative or absolute paths.

Performs targeted search-and-replace operations within an existing file using an array of `{search, replace}` blocks. Ideal for localized changes. Supports plain text or regex search (`useRegex: true`) and replacing all occurrences (`replaceAll: true`). Accepts relative or absolute paths. File must exist.

Lists files and directories within a specified path. Options include recursive listing (`includeNested: true`) and limiting the number of entries (`maxEntries`). Returns a formatted tree structure. Accepts relative or absolute paths.

Permanently removes a specific file. Accepts relative or absolute paths.

Permanently removes a directory. Use `recursive: true` to remove non-empty directories and their contents (use with caution!). Accepts relative or absolute paths.

Creates a new directory at the specified path. By default (`create_parents: true`), it also creates any necessary parent directories. Accepts relative or absolute paths.

Moves or renames a file or directory from a source path to a destination path. Accepts relative or absolute paths for both.

Copies a file or directory from a source path to a destination path. For directories, it copies recursively by default (`recursive: true`). Accepts relative or absolute paths.

Overview

What is Filesystem MCP Server?

Filesystem MCP Server is a TypeScript-based Model Context Protocol server that provides a secure, platform-agnostic interface for AI agents to interact with the local filesystem. It supports both STDIO and Streamable HTTP transports, enabling reading, writing, updating, and managing files and directories with robust security and logging.

How to use Filesystem MCP Server?

Install dependencies with npm install, build with npm run build, then run node dist/index.js (or npm start). Configure via environment variables (.env file supported). Add the server to your MCP client’s configuration with the appropriate transport (STDIO command node with argument path to dist/index.js, or HTTP URL). HTTP transport requires setting MCP_AUTH_SECRET_KEY for JWT authentication.

Key features of Filesystem MCP Server

Comprehensive file and directory operations (read, write, list, delete, move, copy)
Targeted search-and-replace within files via update_file tool
Session-aware default path management with set_filesystem_default
Dual transport: STDIO and HTTP with SSE and JWT authentication
Built‑in path sanitization, Zod input validation, and rate limiting
Logging with Winston, standardized error handling, and modular utilities

Use cases of Filesystem MCP Server

AI agents reading and analyzing file contents in a sandboxed environment
Automated file creation, modification, or overwrite during workflow tasks
Directory and file path management for project scaffolding or data organization
Performing precise, targeted updates within existing files without rewriting the whole file

FAQ from Filesystem MCP Server

What transports are supported?

The server supports STDIO for direct process communication and HTTP (Express.js) with Server‑Sent Events and JWT authentication. Select via the MCP_TRANSPORT_TYPE environment variable.

How do I restrict filesystem access to a specific directory?

Set the FS_BASE_DIRECTORY environment variable to an absolute or project‑relative path. All file operations are then restricted to that directory and its subdirectories. If unset, a warning is logged and no restriction is applied.

What are the main tools exposed by the server?

Tools include set_filesystem_default, read_file, write_file, update_file, list_directory, delete_file, move_file, copy_file, and others for comprehensive filesystem interaction.

Is authentication required for HTTP transport?

Yes, when MCP_TRANSPORT_TYPE is set to http, the MCP_AUTH_SECRET_KEY environment variable is required (minimum 32 characters) for JWT‑based authentication. STDIO transport does not require authentication.

What runtime dependencies does the server need?

The server requires Node.js to run the compiled JavaScript (dist/index.js). It is built with TypeScript 5.8.3 and depends on the MCP SDK, Express.js (for HTTP), Zod (validation), Winston (logging), and other npm packages.

Comments

More Files & Storage MCP servers

Filesystem

modelcontextprotocol

Model Context Protocol Servers

88.1K

md-pdf-mcp (Markdown to PDF MCP Server)

seanivore

Markdown To PDF Conversion MCP

File Context Server

bsmi021

A Model Context Protocol (MCP) server that provides file system context to Large Language Models (LLMs). This server enables LLMs to read, search, and analyze code files with advanced caching and real-time file watching capabilities.

Storacha MCP Storage Server

storacha

Storacha MCP storage server - self-sovereign data for your AI applications.

Google Drive