io.github.j0hanz/filesystem-context
π Read-only MCP server for secure filesystem exploration, searching, and analysis
Ask AI about io.github.j0hanz/filesystem-context
Powered by Claude Β· Grounded in docs
I know everything about io.github.j0hanz/filesystem-context. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 + SSE transports with per-session isolation.
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 aget-helpprompt
Requirements
- Node.js >= 24
Quick Start
{
"mcpServers": {
"filesystem-mcp": {
"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-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Or install via CLI:
code --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
Install in VS Code Insiders
Add to .vscode/mcp.json:
{
"servers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Or install via CLI:
code-insiders --add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest"]}'
Install in Cursor
Add to ~/.cursor/mcp.json:
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Visual Studio
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Goose
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Add to LM Studio
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Claude Code
claude mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest
Or add to config:
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Windsurf
Add to ~/.codeium/windsurf/mcp_config.json:
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Amp
amp mcp add filesystem-mcp -- npx -y @j0hanz/filesystem-mcp@latest
Or add to config:
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Cline
Add to cline_mcp_settings.json:
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Codex CLI
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in GitHub Copilot
Add to .vscode/mcp.json:
{
"servers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Warp
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Kiro
Add to .kiro/settings/mcp.json:
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Gemini CLI
Add to ~/.gemini/settings.json:
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Zed
Add to ~/.config/zed/settings.json:
{
"context_servers": {
"filesystem-mcp": {
"settings": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
}
Install in Augment
Add to VS Code settings.json under augment.advanced:
{
"augment.advanced": {
"mcpServers": [
{
"id": "filesystem-mcp",
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
]
}
}
Install in Roo Code
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Install in Kilo Code
{
"mcpServers": {
"filesystem-mcp": {
"command": "npx",
"args": ["-y", "@j0hanz/filesystem-mcp@latest"]
}
}
}
Use Cases
Explore and Understand a Codebase
Discover project structure and navigate unfamiliar repositories. Start with roots to see allowed directories, use tree for an overview, find to locate files by pattern, and read or read_many to inspect contents.
Relevant tools: roots, ls, find, tree, read, read_many, stat
Search Across Files
Locate specific code patterns, function definitions, or configuration values across a project. Use grep for content search with regex support and find for file name matching.
Relevant tools: grep, find
Edit and Refactor Code
Make precise, targeted edits to source files. Use edit for surgical replacements with dry-run preview, or search_and_replace for bulk changes across multiple files matching a glob pattern.
Relevant tools: edit, search_and_replace, write
Diff and Patch Workflow
Compare file versions and apply patches. Generate a unified diff with diff_files, preview with apply_patch(dryRun: true), then apply. Supports both single-file and multi-file patches (best-effort per file with per-file results[]).
Relevant tools: diff_files, apply_patch
File Management
Create directories, move/rename files, delete files, and verify file integrity via SHA-256 hashing.
Relevant tools: mkdir, mv, rm, calculate_hash, write
Architecture
[MCP Client]
|
| Transport: stdio (default) or Streamable HTTP + SSE (--port)
v
[MCP Server: filesystem-mcp]
| Entry: src/index.ts -> src/server/bootstrap.ts
|
+-- initialize / initialized
|
+-- tools/call ββββββββββββββββββββββββββββββββββββββββββ
| +-- [roots] β List allowed workspace roots
| +-- [ls] β List directory contents
| +-- [find] β Find files by glob
| +-- [tree] β Render directory tree
| +-- [read] β Read file contents
| +-- [read_many] β Read multiple files
| +-- [stat] β Get file metadata
| +-- [stat_many] β Get multiple file metadata
| +-- [grep] β Search file contents
| +-- [mkdir] β Create directory
| +-- [write] β Write file
| +-- [edit] β Edit file (string replacements)
| +-- [mv] β Move/rename file
| +-- [rm] β Delete file
| +-- [calculate_hash] β SHA-256 hash
| +-- [diff_files] β Unified diff
| +-- [apply_patch] β Apply unified patch
| +-- [search_and_replace]β Bulk search & replace
|
+-- resources/read ββββββββββββββββββββββββββββββββββββββ
| +-- internal://instructions
| +-- internal://tool-catalog
| +-- internal://workflows
| +-- internal://tool-info/{name}
| +-- filesystem-mcp://result/{id}
| +-- filesystem-mcp://metrics
|
+-- prompts/get βββββββββββββββββββββββββββββββββββββββββ
| +-- get-help (optional topic argument)
|
+-- Capabilities: logging, resources, tools, prompts, completions, tasks
Request Lifecycle
[Client] -- initialize {protocolVersion, capabilities} --> [Server]
[Server] -- {protocolVersion, capabilities, serverInfo} --> [Client]
[Client] -- notifications/initialized --> [Server]
[Client] -- tools/call {name, arguments} --> [Server]
[Server] -- validate(inputSchema) --> [Handler]
[Handler] -- {content: [{type, text}], structuredContent?, isError?} --> [Client]
MCP Surface
Tools
roots
List allowed workspace roots. Call first β all other tools are scoped to these directories.
No parameters.
ls
List immediate directory contents: name, path, type, size, modified date.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | no | Base directory (default: root) |
includeHidden | boolean | no | Include dotfiles. Default: false |
includeIgnored | boolean | no | Include ignored items (node_modules, .git). Default: false |
maxDepth | integer | no | Max recursion depth (1-100) when pattern is provided |
maxEntries | integer | no | Max entries before truncation. Default: 1000, Max: 10000 |
sortBy | enum | no | name | size | modified | type. Default: name |
pattern | string | no | Glob filter (e.g. **/*.ts) |
includeSymlinkTargets | boolean | no | Resolve symlink targets. Default: false |
cursor | string | no | Pagination cursor from a previous response |
find
Find files by glob pattern. Returns matching files with metadata.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | no | Base directory (default: root) |
pattern | string | yes | Glob pattern (e.g. **/*.ts) |
maxResults | integer | no | Max results (1-100000). Default: 1000 |
includeIgnored | boolean | no | Include ignored items. Default: false |
includeHidden | boolean | no | Include dotfiles. Default: false |
sortBy | enum | no | path | name | size | modified. Default: path |
maxDepth | integer | no | Max directory depth (0-1000) |
cursor | string | no | Pagination cursor |
tree
Render a directory tree with bounded recursion. Returns ASCII tree + structured JSON.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | no | Base directory (default: root) |
maxDepth | integer | no | Depth (0 = root node only). Default: 10, Max: 100 |
maxEntries | integer | no | Max entries. Default: 5000, Max: 100000 |
includeHidden | boolean | no | Include dotfiles. Default: false |
includeIgnored | boolean | no | Include ignored items. Default: false |
read
Read text file contents. Use head to preview first N lines of large files.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Absolute path to file |
head | integer | no | Read first N lines (1-100000) |
startLine | integer | no | Start line (1-based, inclusive) |
endLine | integer | no | End line (1-based, inclusive). Requires startLine |
read_many
Read multiple text files in one request.
| Parameter | Type | Required | Description |
|---|---|---|---|
paths | string[] | yes | Files to read (1-100 paths) |
head | integer | no | Read first N lines of each file |
startLine | integer | no | Start line (1-based) per file |
endLine | integer | no | End line (1-based) per file |
stat
Get file/directory metadata: size, modified, permissions, mime, tokenEstimate.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Absolute path to file or directory |
stat_many
Get metadata for multiple files/directories in one request.
| Parameter | Type | Required | Description |
|---|---|---|---|
paths | string[] | yes | File/directory paths (1-100) |
grep
Search file contents (grep-like). Returns matching lines with optional context.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | no | Base directory (default: root) |
pattern | string | yes | Search text or RE2 regex when isRegex=true |
isRegex | boolean | no | Treat pattern as RE2 regex. Default: false |
caseSensitive | boolean | no | Case-sensitive matching. Default: false |
wholeWord | boolean | no | Match whole words only. Default: false |
contextLines | integer | no | Lines of context before/after (0-50). Default: 0 |
maxResults | integer | no | Max match rows (1-100000). Default: 100 |
filePattern | string | no | Glob for candidate files (e.g. **/*.ts) |
includeHidden | boolean | no | Include dotfiles. Default: false |
includeIgnored | boolean | no | Include ignored items. Default: false |
mkdir
Create a new directory (recursive). Idempotent.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | no | Absolute path to directory to create |
paths | string[] | no | Multiple directories to create. Either path or paths required |
write
Write content to a file, overwriting all existing content. Creates parent directories if needed.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Absolute path to file |
content | string | yes | Content to write |
edit
Apply sequential literal string replacements (first occurrence per edit). Use dryRun to preview.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Absolute path to file |
edits | array | yes | List of {oldText, newText} replacements |
dryRun | boolean | no | Preview edits without writing. Default: false |
ignoreWhitespace | boolean | no | Treat whitespace sequences as equivalent. Default: false |
mv
Move or rename a file or directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
source | string | no | Single path to move (deprecated: use sources) |
sources | string[] | no | Paths to move. Either source or sources required |
destination | string | yes | Destination path |
rm
Permanently delete a file or directory. Irreversible.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Absolute path to file or directory |
recursive | boolean | no | Delete non-empty directories. Default: false |
ignoreIfNotExists | boolean | no | No error if missing. Default: false |
calculate_hash
Calculate SHA-256 hash of a file or directory.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Absolute path to file or directory |
diff_files
Generate a unified diff between two files. Output feeds directly into apply_patch.
| Parameter | Type | Required | Description |
|---|---|---|---|
original | string | yes | Path to original file |
modified | string | yes | Path to modified file |
context | integer | no | Lines of context in diff output |
ignoreWhitespace | boolean | no | Ignore leading/trailing whitespace. Default: false |
stripTrailingCr | boolean | no | Strip trailing carriage returns. Default: false |
apply_patch
Apply a unified diff patch to one or more files. Single-file: throws on failure. Multi-file: best-effort per file with results[]. Workflow: diff_files -> apply_patch(dryRun) -> apply_patch.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | yes | Path to file (single) or base directory (multi-file patch) |
patch | string | yes | Unified diff with @@ hunk headers (single or multi-file) |
fuzzFactor | integer | no | Max fuzzy mismatches per hunk (0-20) |
autoConvertLineEndings | boolean | no | Auto-convert line endings. Default: true |
dryRun | boolean | no | Validate without writing. Default: false |
search_and_replace
Bulk search-and-replace across files matching a glob. Replaces all occurrences per file. Always dryRun: true first.
| Parameter | Type | Required | Description |
|---|---|---|---|
path | string | no | Base directory (default: root) |
filePattern | string | yes | Glob pattern (e.g. **/*.ts) |
searchPattern | string | yes | Text to search. RE2 regex when isRegex=true |
replacement | string | yes | Replacement text. Supports $1, $2 with regex |
isRegex | boolean | no | Treat as RE2 regex. Default: false |
dryRun | boolean | no | Preview matches with diff. Default: false |
includeHidden | boolean | no | Include dotfiles. Default: false |
includeIgnored | boolean | no | Include ignored items. Default: false |
returnDiff | boolean | no | Return diff even when not dry-run. Default: false |
Resources
| Resource | URI | MIME Type | Description |
|---|---|---|---|
| Instructions | internal://instructions | text/markdown | Comprehensive usage rules and guidelines |
| Tool Catalog | internal://tool-catalog | text/markdown | Tool selection guide and data flow map |
| Workflows | internal://workflows | text/markdown | Standard operating procedures for exploration, search, edit, patch |
| Tool Info | internal://tool-info/{name} | text/markdown | Per-tool contract details, nuances, gotchas |
| Result Cache | filesystem-mcp://result/{id} | text/markdown | Ephemeral cached tool output (large results externalized here) |
| Metrics | filesystem-mcp://metrics | text/markdown | Live per-tool call/error/avgDurationMs snapshot |
Prompts
| Prompt | Arguments | Description |
|---|---|---|
get-help | topic (optional) | Return usage instructions. Optionally filter by section heading prefix |
MCP Capabilities
| Capability | Status | Evidence |
|---|---|---|
logging | confirmed | src/server/bootstrap.ts β registered in capabilities |
resources | confirmed | src/server/bootstrap.ts β 6 resources registered |
tools | confirmed | src/server/bootstrap.ts β 18 tools registered |
prompts | confirmed | src/server/bootstrap.ts β get-help prompt registered |
completions | confirmed | src/completions.ts β path + topic auto-completion |
tasks | confirmed | src/server/bootstrap.ts β optional task support (list, cancel, requests) |
Tool Annotations
| Annotation | Tools | Value |
|---|---|---|
readOnlyHint: true | roots, ls, find, tree, read, read_many, stat, stat_many, grep, calculate_hash, diff_files | Read-only, idempotent, non-destructive |
destructiveHint: true | write, edit, rm, mv, search_and_replace, apply_patch | Destructive writes, not idempotent |
idempotentHint: true | mkdir | Idempotent write, non-destructive |
Structured Output
All 18 tools define outputSchema (Zod -> JSON Schema) and return structuredContent alongside text content. Set FS_CONTEXT_STRIP_STRUCTURED=true to strip output schemas from tool definitions (reduces token usage for LLMs that don't use structured output).
Configuration
| Variable | Default | Description |
|---|---|---|
FILESYSTEM_MCP_API_KEY | (none) | Bearer token required when binding HTTP to a non-loopback host |
FILESYSTEM_MCP_MAX_HTTP_SESSIONS | 100 | Max concurrent HTTP sessions (1-10,000) |
FILESYSTEM_MCP_HTTP_HOST | 127.0.0.1 | HTTP server bind address |
FS_CONTEXT_MAX_REQUEST_BYTES | 4194304 (4 MB) | Max HTTP request body size (1 KB - 256 MB) |
FS_CONTEXT_MAX_INLINE_CHARS | (auto) | Max inline result chars before externalizing to filesystem-mcp://result/{id} |
FS_CONTEXT_MAX_INLINE_MATCHES | 50 | Max inline search matches before truncation |
FS_CONTEXT_STRIP_STRUCTURED | false | Strip outputSchema from tool definitions |
FS_CONTEXT_DIAGNOSTICS | false | Enable diagnostic logging |
FS_CONTEXT_DIAGNOSTICS_DETAIL | false | Enable detailed diagnostic output |
FS_CONTEXT_TOOL_LOG_ERRORS | false | Log tool errors to stderr |
FS_CONTEXT_SEARCH_WORKERS_DEBUG | false | Debug logging for search worker pool |
HTTP Endpoints
When started with --port <number>, the server exposes a single MCP endpoint:
| Method | Path | Purpose |
|---|---|---|
POST | /mcp | Initialize session or send requests (Streamable HTTP) |
GET | /mcp | Server-Sent Events stream for a session |
DELETE | /mcp | Terminate a session |
Required headers:
mcp-protocol-versionβ use the negotiated MCP protocol version on post-initialize HTTP requestsmcp-session-idβ required forGET/DELETE(returned byPOSTon initialize)
Authentication: Requests to non-loopback HTTP binds require FILESYSTEM_MCP_API_KEY; clients must then send Authorization: Bearer <key>. Loopback-only binds may omit auth for local use. Uses SHA-256 timing-safe comparison.
CORS: Only localhost origins allowed (127.0.0.1, ::1, localhost).
Security
| Control | Status | Evidence |
|---|---|---|
| Path sandboxing | confirmed | src/lib/paths.ts β all paths validated against allowed roots |
| Traversal prevention | confirmed | src/lib/paths.ts β resolved paths checked after normalization |
| Symlink escape prevention | confirmed | src/__tests__/security.test.ts β symlink boundary enforcement |
| Sensitive file denylist | confirmed | src/lib/constants.ts β blocks .git, .env*, SSH keys, certs, secrets |
| Origin validation | confirmed | src/server/bootstrap.ts β localhost-only Origin allowlist |
| Bearer auth | confirmed | src/server/bootstrap.ts β optional FILESYSTEM_MCP_API_KEY with timing-safe compare |
| Input validation | confirmed | src/schemas.ts β Zod strict schemas on all tool inputs |
| Request body limit | confirmed | src/server/bootstrap.ts β configurable max request size (413 on overflow) |
| Remote bind guard | confirmed | src/server/bootstrap.ts β refuses non-loopback bind without FILESYSTEM_MCP_API_KEY |
Development
| Script | Command | Purpose |
|---|---|---|
dev | tsc --watch | Watch mode TypeScript compilation |
dev:run | node --env-file=.env --watch dist/index.js | Run server with auto-reload |
start | node dist/index.js | Run production server |
build | node scripts/tasks.mjs build | Clean build |
test | node scripts/tasks.mjs test | Build + run all tests |
test:fast | node --test --import tsx/esm src/__tests__/**/*.test.ts | Run tests without build |
lint | eslint . | Lint source |
type-check | node scripts/tasks.mjs type-check | Type-check src + tests |
format | prettier --write . | Format code |
inspector | npm run build && npx @modelcontextprotocol/inspector | Launch MCP Inspector |
Build and Release
- CI:
.github/workflows/release.ymlβ runs lint, type-check, test, build before tagging/publishing. - Docker: Multi-stage build with
node:24-alpine. Builder compiles TypeScript + native modules (re2); release stage runs as non-rootmcpuser. - npm:
npm run prepublishOnlyruns lint + type-check + build.
Troubleshooting
- "No allowed directories" β Pass at least one directory argument or use
--allow-cwd. - Sensitive file blocked β Files matching the denylist (
.env*,.git, SSH keys) are blocked by design. Checksrc/lib/constants.tsfor the full list. - Large result externalized β When tool output exceeds inline limits, it's cached as a resource at
filesystem-mcp://result/{id}. Read the resource URI to get the full content. - Stdio: logs on stdout β Keep logs on stderr only. The server uses
console.errorfor diagnostics. - HTTP 413 β Request body exceeds
FS_CONTEXT_MAX_REQUEST_BYTES. Increase the limit or reduce payload size. - HTTP 401 β
FILESYSTEM_MCP_API_KEYis set but the request is missing or has an incorrectAuthorization: Bearerheader.
Credits
| Dependency | Description |
|---|---|
| @modelcontextprotocol/sdk | MCP TypeScript SDK |
| commander | CLI argument parsing |
| diff | Unified diff generation and patch application |
| ignore | .gitignore pattern matching |
| re2 | Safe RE2 regex engine (no ReDoS) |
| safe-regex2 | Regex safety validation |
| zod | Schema validation and JSON Schema generation |
Contributing and License
- License: MIT
- Contributions welcome via pull requests.
