README.md
MCP Server that enables LLMs to interact with the local filesystem.
Filesystem MCP Server
A local filesystem MCP server that lets LLMs and AI agents read, write, search, diff, patch, and manage files safely and efficiently. Built for reliable, structured, and controlled filesystem interaction.
Overview
A secure, production-ready Model Context Protocol server that gives AI assistants controlled access to the local filesystem. All operations are sandboxed to explicitly allowed directories with path traversal prevention, sensitive file blocking, and optional Bearer token authentication.
Supports stdio (default) and Streamable HTTP transport with SSE support. HTTP sessions are implemented with isolated per-session server state.
Key Features
- 18 filesystem tools — read, write, search, diff, patch, hash, and bulk operations with structured output schemas
- Security-first — path validation, symlink escape prevention, sensitive file denylist, localhost-only CORS, optional API key auth
- Dual transport — stdio for local use, Streamable HTTP with SSE for networked/multi-session deployments
- Structured output — all tools return typed
outputSchema/structuredContentfor reliable LLM parsing - Self-documenting — 6 built-in resources (
internal://instructions,internal://tool-catalog, etc.) and 4 built-in prompts (get-help,compare-files,analyze-path,get-tool-help)
Requirements
- Node.js >= 24
Quick Start
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Docker
docker run -i --rm -v /path/to/project:/workspace:ro ghcr.io/j0hanz/filesystem-mcp /workspace
Or using Docker Compose:
services:
filesystem-mcp:
build: .
stdin_open: true
volumes:
- ./:/projects/workspace:ro
command: ['/projects/workspace']
CLI Usage
filesystem-mcp [options] [allowedDirs...]
Arguments:
allowedDirs Directories the server can access
Options:
--allow-cwd Allow the current working directory as an additional root
--port <number> Enable HTTP transport on the given port
-v, --version Display server version
-h, --help Display help
Examples:
$ npx @j0hanz/filesystem-mcp@latest /path/to/project
$ npx @j0hanz/filesystem-mcp@latest --allow-cwd
$ npx @j0hanz/filesystem-mcp@latest --port 3000 /path/to/project
Client Configuration
Install in VS Code
Add to .vscode/mcp.json:
{
"servers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0han
Tools (1)
read, write, search, diff, patch, hashA suite of 18 filesystem tools for managing files with structured output schemas.Configuration
claude_desktop_config.json
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}Try it
→List all files in the current directory and summarize the project structure.
→Read the contents of README.md and suggest improvements to the installation section.
→Search for all files containing the string 'TODO' in the src directory.
→Create a new file named 'notes.txt' and add a summary of our current progress.
→Compare the changes between 'config.json' and 'config.json.bak'.