set_filesystem_defaultLABSCO SUMMARY
Set the base directory before anything else.
It is optional, and leaving it unset means the tools can reach anywhere the process can — the server logs a warning and carries on, which is easy to miss. With it set, plus the session default path, an agent works in relative paths inside one tree, and the targeted replace tool means editing a config file does not require the model to reproduce the whole thing correctly.
What it is
A TypeScript MCP server exposing filesystem operations to AI agents, with path sanitization, schema-validated inputs, and a choice of stdio for local use or HTTP with JWT authentication for network use.
What you get
read_fileandwrite_filefor whole-file reads and writes, creating parent directories as neededupdate_file— targeted search-and-replace blocks within an existing file, with plain text or regex, and an option to replace every occurrenceset_filesystem_default— a default absolute path for the session, so later calls can use relative pathslist_fileswith recursive listing, an entry cap, and a formatted tree as outputcreate_directory,delete_file,delete_directorywith an explicit recursive flag,move_pathandcopy_path- Built-in path sanitization against directory traversal, and Zod validation on every input
Requirements
Clone, install and build with npm, then point your client at the built entry point. MCP_TRANSPORT_TYPE chooses stdio or http; the HTTP path binds MCP_HTTP_HOST and MCP_HTTP_PORT and requires MCP_AUTH_SECRET_KEY of at least 32 characters for JWT authentication. Set FS_BASE_DIRECTORY to confine all operations to one directory tree — leave it unset and operations are not restricted, which the project warns against.
Setup effort
Build from source — clone the repository and build it, then point your client at the built dist/index.js
USE CASES
01
Making a small edit to a large file
Replace just the block that changes, instead of having the model rewrite the file and hope it kept the rest intact.
02
Working in one project directory
Set the session default once, then refer to everything by relative path.
03
Getting the lay of the land
List recursively with an entry cap and read the tree, rather than pulling every file into context.
04
Reorganising a folder
Create the new directories, then move or copy paths into them in one pass.
05
Fencing an agent into one tree
Point the base directory at a sandbox folder so nothing outside it can be read or written.
10 tools
Listed in project docs. Your client may show a different list.
read_filewrite_fileupdate_filelist_filesdelete_filedelete_directorycreate_directorymove_pathcopy_pathBEFORE YOU INSTALL
What to know first
Tools you get
10 tools named in the project's documentation.
Requires
Node.js and npm, to build from source
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Clone the repository and build it, then point your client at the built dist/index.js. This one is built from source rather than installed with a single command.
Server setup
TERMINAL
git clone https://github.com/cyanheads/filesystem-mcp-server.git
cd filesystem-mcp-server
npm install
npm run buildThe build writes the server to dist/index.js. In the client configuration, <YOUR_PATH_TO_FILESYSTEM_MCP_SERVER>/dist/index.js is the full path to that file. Set FS_BASE_DIRECTORY in env to confine every operation to one directory tree — without it, operations are not restricted.
MCP Clients
Any MCP client
ANY MCP CLIENT · JSON
{
"mcpServers": {
"filesystem_stdio": {
"command": "node",
"args": [
"<YOUR_PATH_TO_FILESYSTEM_MCP_SERVER>/dist/index.js"
],
"env": {
"MCP_LOG_LEVEL": "debug"
},
"disabled": false,
"autoApprove": []
}
}
}
