home / mcp / filesystem mcp server
Provides navigation, file management, search, and analysis tools for local filesystem operations within allowed directories.
Configuration
View docs{
"mcpServers": {
"j0hanz-filesystem-mcp": {
"command": "npx",
"args": [
"-y",
"@j0hanz/filesystem-mcp@latest",
"C:\\path\\to\\allowed\\directory"
]
}
}
}Filesystem MCP lets you interact with your local filesystem through an MCP client, providing guided navigation, file management, search, and analysis within a securely restricted set of directories you specify at startup.
You use the server by connecting an MCP client that supports stdio transport. Start the server command, then issue tool operations from your client to navigate directories, read and modify files, search for content, and inspect metadata. All actions occur only within the allowed directories you configure at startup, keeping your workspace safe while enabling powerful file operations.
Prerequisites you need before installing are Node.js version 24 or newer and npm. With these installed, you can install and run the server in a few straightforward ways.
Quickstart using npx (recommended):
Run directly with npx:
npx -y @j0hanz/filesystem-mcp@latest "C:\path\to\allowed\directory"Use a Docker container to run the server and mount your workspace directory as a volume. Pass the container path to the server as an argument.
docker run -i --rm \
-v /path/to/your/project:/projects/workspace:ro \
ghcr.io/j0hanz/filesystem-mcp:latest \
/projects/workspaceIf you prefer building from source, follow these steps to install dependencies, build, and run.
# 1) Clone the repository
# 2) Install dependencies
npm ci
# 3) Build the project
npm run build
# 4) Run locally
node dist/index.js [options] [directories...]To operate securely, specify the allowed root directories the server can access at startup. You can also allow the current working directory to be an additional root.
# Example startup with allowed directories
node dist/index.js /path/to/allowed/dir1 /path/to/allowed/dir2 --allow-cwdAll file operations are strictly validated against the provided allowed directories. Path traversal is prevented by using directory-restricted checks, and hidden files (those starting with a dot) are excluded by default from listings and searches unless explicitly requested.
This server exposes a set of tools to manage and inspect the filesystem. You can list, read, search, edit, and compare files, as well as inspect metadata and perform batch operations.
- ls: List directory contents, with optional inclusion of hidden files.
- tree: Generate a directory tree visualization.
- roots: List the root directories currently allowed.
- find: Find files matching a glob pattern.
- grep: Search within files using a pattern (regex or literal).
- read: Read contents of a single file.
- read_many: Read multiple files in one call.
- stat: Retrieve metadata for a file.
- stat_many: Retrieve metadata for multiple files.
- calculate_hash: Compute SHA-256 hash for a file.
- mkdir: Create a directory (recursive).
- write: Write or overwrite a file with specified content.
- edit: Apply string-based edits to a file.
- mv: Move or rename a file or directory.
- rm: Remove a file or directory (recursive option available).
- diff_files: Generate a unified diff between two files.
- apply_patch: Apply a unified patch to a file.
- search_and_replace: Perform a search-and-replace across multiple files.
To connect an MCP client, you configure a stdio server with the following command and arguments. This example shows the recommended approach using npx to run the MCP server for a specific allowed directory.
List directory contents with options to include hidden files.
Generate a visual directory tree from a path.
Show the root directories that are allowed for filesystem access.
Find files by glob pattern within allowed directories.
Search file contents using a regular expression or literal text.
Read content from a single file.
Read content from multiple files in one operation.
Retrieve metadata for a given file.
Retrieve metadata for multiple files.
Compute the SHA-256 hash of a file.
Create a directory, recursively if needed.
Write or overwrite a file with specific content.
Edit a file by applying string replacements.
Move or rename a file or directory.
Delete a file or directory, with optional recursive delete.
Generate a unified diff between two files.
Apply a unified patch to a file.
Search across files and replace with a given pattern.