filesystem-context

@j0hanz/filesystem-context

0 Stars 31 次浏览 j0hanz 更新于 2026-08-23

馃攳 Read-only MCP server for secure filesystem exploration, searching, and analysis

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "@j0hanz/filesystem-context-mcp": {
      "args": [
        "@j0hanz/filesystem-context-mcp@1.0.9"
      ],
      "command": "npx"
    }
  }
}

可用工具（5 个）

该服务在 MCP 协议中暴露的工具，AI 可按需调用

tavily_search 14 个参数需填 1 项 Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs.

Search the web for current information on any topic. Use for news, facts, or data beyond your knowledge cutoff. Returns snippets and source URLs.

必填参数：query

tavily_extract 6 个参数需填 1 项 Extract content from URLs. Returns raw page content in markdown or text format.

Extract content from URLs. Returns raw page content in markdown or text format.

必填参数：urls

tavily_crawl 11 个参数需填 1 项 Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth.

Crawl a website starting from a URL. Extracts content from pages with configurable depth and breadth.

必填参数：url

tavily_map 8 个参数需填 1 项 Map a website's structure. Returns a list of URLs found starting from the base URL.

Map a website's structure. Returns a list of URLs found starting from the base URL.

必填参数：url

tavily_research 2 个参数需填 1 项 Perform comprehensive research on a given topic or question. Use this tool when you need to gather information from multiple sources to answer a question or complete a task. Returns a detailed response based on the research findings.

Perform comprehensive research on a given topic or question. Use this tool when you need to gather information from multiple sources to answer a question or complete a task. Returns a detailed response based on the research findings.

必填参数：input

服务介绍

Filesystem MCP

npm version License Node.js Version

MCP Server that enables LLMs to interact with the local filesystem. Provides tools for navigation, search, file management, and analysis — all scoped to allowed directories.

# Overview

Filesystem MCP exposes a rich set of tools for reading, writing, searching, and inspecting files and directories. All operations are strictly bounded to the directories you provide at startup, preventing access to any path outside those roots.

# Key Features

Navigation: List directory contents (ls), render trees (tree), and query workspace roots (roots).
File I/O: Read single or multiple files (read, read_many); write, edit, move, and delete (write, edit, mv, rm).
Search: Find files by glob pattern (find) or search content with full regex support (grep).
Analysis: Metadata and token estimates (stat, stat_many), SHA-256 hashing (calculate_hash), and unified diffs (diff_files).
Patch & Replace: Apply unified patches (apply_patch) and bulk search-and-replace across files (search_and_replace).
Tasks: Long-running tools support background task execution with progress notifications and cancellation.
Large Output Handling: Oversized results are externalized to ephemeral resource URIs instead of truncating inline.
Security: Strict path validation, safe regex via RE2, .gitignore-aware operations, and atomic writes.

# Requirements

Node.js >= 24

# Quick Start

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/allowed/dir"]
    }
  }
}

Run directly:

npx -y @j0hanz/filesystem-mcp@latest /path/to/allowed/dir

# Client Configuration

Or add manually to .vscode/mcp.json:

{
  "servers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "${workspaceFolder}"]
    }
  }
}

CLI:

code - -add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","${workspaceFolder}"]}'

CLI:

code-insiders - -add-mcp '{"name":"filesystem-mcp","command":"npx","args":["-y","@j0hanz/filesystem-mcp@latest","${workspaceFolder}"]}'

Or add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/dir"]
    }
  }
}

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/dir"]
    }
  }
}

claude mcp add filesystem-mcp - - npx -y @j0hanz/filesystem-mcp@latest /path/to/dir

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "npx",
      "args": ["-y", "@j0hanz/filesystem-mcp@latest", "/path/to/dir"]
    }
  }
}

[mcp_servers.filesystem-mcp]
command = "npx"
args = ["-y", "@j0hanz/filesystem-mcp@latest", "${workspaceFolder}"]

docker run -i - -rm \
  -v /path/to/your/project:/projects/workspace:ro \
  ghcr.io/j0hanz/filesystem-mcp:latest \
  /projects/workspace

MCP config:

{
  "mcpServers": {
    "filesystem-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "- -rm",
        "-v",
        "/path/to/project:/projects/workspace:ro",
        "ghcr.io/j0hanz/filesystem-mcp:latest",
        "/projects/workspace"
      ]
    }
  }
}

# MCP Surface

# # Tools

# # # `roots` — List workspace roots

Enumerate the directories the server is allowed to access. Call this first in any session.

No input parameters.

# # # `ls` — List directory contents

List immediate directory contents (non-recursive). Returns name, type, size, and modified date per entry.

# # # `find` — Find files by glob

Locate files matching a glob pattern. Returns relative paths and metadata.

[!TIP]
Supports background task execution with progress reporting.

# # # `tree` — Render directory tree

Returns both an ASCII tree (text) and a structured JSON tree.

# # # `read` — Read file content

Read text content of a single file with optional line-range or head preview.

| Parameter | Type | Required | Default | Description |
| :- -- -- -- -- - | :- -- -- - | :- -- -- -: | :- -- -- - | :- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - |
| path | string | Yes | — | Absolute path to file |
| head | integer | No | — | Read first N lines (1–100,000); mutually exclusive with startLine/endLine |
| startLine | integer | No | — | Start line (1-based, inclusive) |
| endLine | integer | No | — | End line (1-based, inclusive); requires startLine |

Large files return a resourceUri; call resources/read on that URI for full content.

# # # `read_many` — Read multiple files

Batch-read up to 100 files in a single request.

| Parameter | Type | Required | Default | Description |
| :- -- -- -- -- - | :- -- -- -- | :- -- -- -: | :- -- -- - | :- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- |
| paths | string[] | Yes | — | File paths (1–100 items) |
| head | integer | No | — | Read first N lines of each file |
| startLine | integer | No | — | Start line per file |
| endLine | integer | No | — | End line per file (requires startLine) |

Per-file truncationReason can be head, range, or externalized. Total read budget is capped internally.

# # # `stat` — Get file/directory metadata

Returns name, type, size, created/modified/accessed timestamps, permissions, MIME type, and a token estimate (size ÷ 4).

| Parameter | Type | Required | Default | Description |
| :- -- -- -- - | :- -- -- | :- -- -- -: | :- -- -- - | :- -- -- -- -- -- - |
| path | string | Yes | — | Absolute path |

# # # `stat_many` — Get metadata for multiple paths

Batch version of stat.

| Parameter | Type | Required | Default | Description |
| :- -- -- -- - | :- -- -- -- | :- -- -- -: | :- -- -- - | :- -- -- -- -- -- -- -- -- - |
| paths | string[] | Yes | — | Paths (1–100 items) |

# # # `grep` — Search file content

Search for text within files using literal match or RE2 regex. Returns matching lines with optional context.

[!NOTE]
RE2 does not support lookahead, lookbehind, or backreferences. Results exceeding 50 inline matches are externalized via resourceUri.

# # # `calculate_hash` — SHA-256 hash

Compute a SHA-256 hash. For directories, produces a deterministic composite hash of all contained files (lexicographically sorted, .gitignore-aware).

| Parameter | Type | Required | Default | Description |
| :- -- -- -- - | :- -- -- | :- -- -- -: | :- -- -- - | :- -- -- -- -- -- -- -- -- -- -- |
| path | string | Yes | — | File or directory path |

# # # `diff_files` — Generate unified diff

Create a unified diff between two files. Check isIdentical in the response — if true, the files match and no patch is needed.

Large diffs are externalized to a resourceUri.

# # # `mkdir` — Create directory

Create a directory and all missing parent directories (recursive).

| Parameter | Type | Required | Default | Description |
| :- -- -- -- - | :- -- -- | :- -- -- -: | :- -- -- - | :- -- -- -- -- -- -- -- -- -- -- -- |
| path | string | Yes | — | Directory path to create |

# # # `write` — Write file

Create or overwrite a file. Parent directories are created automatically.

| Parameter | Type | Required | Default | Description |
| :- -- -- -- - | :- -- -- | :- -- -- -: | :- -- -- - | :- -- -- -- -- -- -- -- |
| path | string | Yes | — | File path |
| content | string | Yes | — | Content to write |

[!CAUTION]
Overwrites existing file content without confirmation.

# # # `edit` — Edit file

Apply sequential literal string replacements to an existing file. Replaces the first occurrence of each oldText.

| Parameter | Type | Required | Default | Description |
| :- -- -- -- - | :- -- -- -- -- -- -- -- -- -- -- | :- -- -- -: | :- -- -- - | :- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- |
| path | string | Yes | — | File to edit |
| edits | {oldText, newText}[] | Yes | — | Ordered list of replacement operations |
| dryRun | boolean | No | false | Validate edits without writing |

Include 3–5 lines of surrounding context in oldText to uniquely target the location. Unmatched edits are reported in unmatchedEdits.

# # # `mv` — Move or rename

Move or rename a file or directory. Parent directories of the destination are created automatically. Falls back to copy+delete for cross-device moves.

| Parameter | Type | Required | Default | Description |
| :- -- -- -- -- -- - | :- -- -- | :- -- -- -: | :- -- -- - | :- -- -- -- -- -- -- -- |
| source | string | Yes | — | Source path |
| destination | string | Yes | — | Destination path |

# # # `rm` — Delete file or directory

Delete a file or directory.

[!WARNING]
Non-empty directories with recursive: false return E_INVALID_INPUT with guidance to retry using recursive: true.

# # # `apply_patch` — Apply unified patch

Apply a unified diff patch to a file. Always validate with dryRun: true before writing.

If patch application fails, regenerate a fresh patch via diff_files against the current file content and retry.

# # # `search_and_replace` — Search and replace across files

Replace text in all files matching a glob. Replaces all occurrences per file. Use dryRun: true to preview scope before writing.

# # Resources

| URI | Description | MIME Type |
| :- -- -- -- -- -- -- -- -- -- -- -- -- -- -- | :- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- - | :- -- -- -- -- -- -- -- -- |
| internal://instructions | Usage guidance for models | text/markdown |
| internal://tool-catalog | Tool routing and data-flow guide | text/markdown |
| internal://workflows | Explore/search/edit/patch workflows | text/markdown |
| internal://tool-info/{name} | Per-tool nuances and gotchas | text/markdown |
| filesystem-mcp://metrics | Live per-tool metrics snapshot | application/json |
| filesystem-mcp://result/{id} | Ephemeral cached large tool output | varies |

When a tool response includes a resource_link/resourceUri, treat it as authoritative for full payload retrieval and call resources/read with that URI.

# # Prompts

# # Tasks (Background Execution)

The server declares full task capabilities (tasks/list, tasks/cancel). The following tools support task-based invocation with progress notifications:

find, tree, read, read_many, stat_many, grep, mkdir, write, mv, rm, calculate_hash, apply_patch, search_and_replace

Include _meta.progressToken in a tools/call request to receive notifications/progress updates. Use tools/call with a task field to invoke as a background task, then poll tasks/get and retrieve output via tasks/result.

Recommended task follow-up loop:

Start with tools/call + task (optional _meta.progressToken).
Poll tasks/get until terminal status (completed, failed, cancelled).
Fetch final payload with tasks/result.

Task status notifications (notifications/tasks/status) are best-effort and emitted only when the transport/runtime provides a notification sender.

Cancellation semantics:

tasks/cancel is the canonical cancellation API.
Clients should treat E_CANCELLED as cancellation even if a transport/client surfaces a terminal failure shape.

# Configuration

# # CLI

filesystem-mcp [options] [allowedDirs...]

Examples:

#  Single directory
filesystem-mcp /project/src

#  Multiple directories
filesystem-mcp /project/src /project/tests

#  Current working directory
filesystem-mcp - -allow-cwd

#  Combined
filesystem-mcp /project/src - -allow-cwd

# # Allowed Directories

Directories are resolved from three sources, merged at runtime:

CLI arguments — positional directory paths passed at startup.
MCP Roots protocol — directories provided by the connected client after initialization (accepted only if they are within the CLI baseline when CLI directories are set).
- -allow-cwd — the current working directory is added automatically.

[!TIP]
If no directories are configured at startup and the connected client does not supply MCP Roots, all tool calls will fail. Pass at least one directory argument or use - -allow-cwd.

# # Compatibility

Set FS_CONTEXT_STRIP_STRUCTURED=1 to strip structuredContent from tool results and outputSchema from tool definitions for compatibility with clients that only consume text content.

# Security

Path validation: All operations use isPathWithinDirectories to prevent path traversal attacks.
Glob safety: Glob patterns are validated to reject absolute paths and .. traversal before execution.
Safe regex: re2 executes regex (no catastrophic backtracking); safe-regex2 rejects unsafe patterns before use.
Hidden files: Excluded from listings and searches by default; opt in with includeHidden: true.
Ignored directories: node_modules, .git, dist, and similar directories are excluded by default; opt in with includeIgnored: true.
Windows safety: Reserved device names (e.g. CON, NUL, COM1) and drive-relative paths (e.g. C:path) are rejected at the CLI.
Input limits: Paths are bounded to 4,096 characters; patterns to 1,000 characters.
Atomic writes: File writes use an atomic write-then-rename strategy to prevent partial writes.
Docker: The container runs as a non-root user (mcp).
HTTP host binding: The HTTP transport binds to 127.0.0.1 by default. Setting FILESYSTEM_MCP_HTTP_HOST=0.0.0.0 binds to all network interfaces and exposes the server externally — only do this behind a trusted reverse proxy with FILESYSTEM_MCP_API_KEY configured.

[!IMPORTANT]
All diagnostic output goes to stderr. Tool handlers must never write to stdout, as doing so would corrupt the stdio transport.

# Development

# # Install

npm ci

# # Scripts

# # MCP Inspector

npm run inspector

Or manually:

npx @modelcontextprotocol/inspector node dist/index.js /path/to/dir

# Build & Release

Releases are triggered manually via GitHub Actions (workflow_dispatch). The pipeline:

Bumps package.json and server.json to the selected version (patch / minor / major or custom).
Runs lint, type-check, tests, and build.
Commits, tags (vX.Y.Z), and creates a GitHub Release with auto-generated notes.
Publishes to npm (@j0hanz/filesystem-mcp) with OIDC provenance.
Publishes to the MCP Registry (io.github.j0hanz/filesystem-mcp).
Builds and pushes the Docker image (ghcr.io/j0hanz/filesystem-mcp) for linux/amd64 and linux/arm64.

The Glama listing requires a separate manual release step on the Glama dashboard.

# # Docker Build (local)

docker build -t filesystem-mcp .

# HTTP Conformance Notes

For Streamable HTTP clients, this server enforces the following behavior:

Session-bound requests must include MCP-Protocol-Version: 2025-11-25; missing or unsupported values return 400.
Requests with invalid or expired mcp-session-id return 404.
Initialize requests continue to be accepted without a session ID.

# Backlog Hardening (Planned)

The following hardening items are intentionally tracked as follow-up work:

Add a TTL-evicting task store for long-lived HTTP deployments to bound memory usage.
Add an optional per-session roots isolation mode for multi-tenant HTTP deployments.

# Troubleshooting

No directories configured
If no directories are provided at startup and the client doesn't supply MCP Roots, all tool calls fail with E_ACCESS_DENIED. Use roots to inspect configured roots.

Path outside allowed directories
Tools return E_ACCESS_DENIED when a path is outside all allowed roots. Use roots first to see what is available.

Empty directory or no matches
find and grep return empty results rather than errors when nothing matches. Verify the pattern and root path.

Pattern rejected (E_INVALID_PATTERN)
Glob patterns cannot be absolute or use .. to traverse upward. RE2 patterns are validated before use.

Non-empty directory delete fails
rm returns E_INVALID_INPUT for non-empty directories without recursive: true. Either set recursive: true or remove contents first.

Patch application failed
apply_patch requires valid unified hunk headers (@@ -N,M +N,M @@). Regenerate the patch with diff_files against the current file content and retry.

Stdout contamination
The server uses stdio transport. Never write to stdout in custom integrations. All diagnostic output goes to stderr. For Claude Desktop, check ~/Library/Logs/Claude/mcp*.log (macOS) or the equivalent on Windows.

# License

MIT

查看源码项目主页

MCP 服务配置

可用工具 （5 个）

服务介绍

Filesystem MCP

# Overview

# Key Features

# Requirements

# Quick Start

# Client Configuration

# MCP Surface

# # Tools

# # # roots — List workspace roots

# # # ls — List directory contents

# # # find — Find files by glob

# # # tree — Render directory tree

# # # read — Read file content

# # # read_many — Read multiple files

# # # stat — Get file/directory metadata

# # # stat_many — Get metadata for multiple paths

# # # grep — Search file content

# # # calculate_hash — SHA-256 hash

# # # diff_files — Generate unified diff

# # # mkdir — Create directory

# # # write — Write file

# # # edit — Edit file

# # # mv — Move or rename

# # # rm — Delete file or directory

# # # apply_patch — Apply unified patch

# # # search_and_replace — Search and replace across files