Filesystem Context MCP Server logo

Filesystem Context MCP Server

by j0hanz

Read-only filesystem exploration over MCP with folder listing, file search, text search, metadata, reads, and diffs.

Install Filesystem Context MCP Server

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "j0hanz-filesystem-context-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@j0hanz/filesystem-mcp@latest"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Automated check passed— started and listed 14 tools correctly ().

Overview

j0hanz/filesystem-context-mcp-server exposes a read-only view of approved local folders through MCP. Its tools list directory trees, find files by name or glob, search file contents with literal text or regular expressions, inspect metadata, read text or media, and compare files. Symlink protection helps keep traversal within the permitted filesystem scope. Use it when an agent needs to inspect code, logs, documents, or other local files without write access.

Use cases

  • Inspect a repository structure before making code changes
  • Find files matching a glob pattern across a project
  • Search source code or logs for text and regular expressions
  • Read selected lines from a large log file
  • Compare configuration or source files with a unified diff

Key features

  • Read-only filesystem access
  • Approved-folder scoping with symlink protection
  • Glob-based file discovery
  • Literal and regular-expression text search
  • Metadata and token estimates before reading
  • Unified file diffs

Tools14

What Filesystem Context MCP Server lets your agent do. Expand a tool for its parameters.

Verified live~7.4k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked

Recent health check succeeded.

22/22 checks healthy over the last 97d

What it can do

From the 14 tools this server returned when we ran it; 14 declare their own safety hints.

Can delete or modify data · 7Makes network requests · 3Read-only tools · 7
Network at startup3 connections
Files written at startupNone
Install scriptsNone
npm provenanceSigned build
Package age278 days
Maintainers1

Observed 2026-11-16 in an isolated sandbox. A description of reach, not a security audit.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 4d ago via OSV.dev · @j0hanz/filesystem-mcp@latest (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars32Stargazers on the source repository.
npm downloads7.9kPackage downloads in the last 30 days.
Last commit2d agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed14Callable tools this server registers over MCP.
Directory activity4 viewsConfig copies, upvotes, and views on AllMCPs.

How Filesystem Context MCP Server works

What j0hanz/filesystem-context-mcp-server does

j0hanz/filesystem-context-mcp-server gives MCP-compatible AI applications controlled access to local folders for filesystem exploration and analysis. It is intended for read-only workflows: agents can discover files, inspect their contents and metadata, search across a project, and compare two files without changing them.

Access is limited to folders configured for the server. Symlink protection helps prevent directory traversal from escaping the allowed filesystem scope. The server exposes the folders it can use through list_roots, so an agent can establish its available scope before inspecting files.

How it works

The server runs locally and communicates with an AI client through MCP. Configure one or more permitted folder paths, then connect the client to the server process. Requests are handled through focused filesystem tools rather than unrestricted shell access.

Directory exploration uses list, which returns a tree-style view of a folder. find_files accepts file names or glob patterns, while search_text searches file contents using literal text or a regular expression and can include surrounding context lines. Before reading a large file, stat can report its size and an estimated token count.

read can return an entire text file or selected lines, including the beginning or end of a file. Images and audio are returned as media; other non-text content is represented as binary data. diff compares two files and returns a unified diff.

Setup and configuration

Node.js 24 or later is required. The package can be started with npx, using the @j0hanz/filesystem-mcp@latest package reference and one or more folder paths as arguments. Replace the example path with a directory the agent should be allowed to inspect.

A typical stdio configuration uses a command such as npx with these arguments:

  • -y
  • @j0hanz/filesystem-mcp@latest
  • One or more permitted folder paths

The server can also be used over Streamable HTTP by starting it with a port option. Claude Desktop offers a downloadable extension, while VS Code and Cursor provide MCP installation links and configuration examples.

Tools and capabilities

  • list_roots: Shows the folders available to the server.
  • list: Produces a tree-style listing for a folder.
  • find_files: Matches files by name or glob pattern.
  • search_text: Searches file contents with text or regular expressions and optional context.
  • stat: Returns file size, timestamps, type, permissions, and a token estimate without reading the file.
  • read: Reads complete files or selected lines and returns supported media appropriately.
  • diff: Generates a unified comparison between two files.

Limitations and notes

Only configured folders are available to the agent, and symlink protection limits traversal through filesystem links. The server is suitable for inspection and comparison rather than file modification. Reading very large files may consume substantial context, so stat, line ranges, head, tail, and targeted searches can help constrain responses. Node.js 24 or newer is needed to run the package.

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Filesystem Context MCP Server

j0hanz/filesystem-context-mcp-server is an MCP server that connects AI clients to approved local folders for read-only filesystem analysis. Its main tools list directories, find files, search text, inspect metadata, read text or media, and generate unified diffs while limiting access to configured paths.

Install it by running the `@j0hanz/filesystem-mcp@latest` package with `npx` and passing one or more permitted folder paths. Add that command to your MCP client configuration, then restart the client. Node.js 24 or later is required.

Yes, j0hanz/filesystem-context-mcp-server works with Cursor. Add an MCP entry that runs `npx -y @j0hanz/filesystem-mcp@latest` and include the folder path in the command arguments, or use Cursor's installation link.

Yes, `search_text` searches file contents using literal text or regular expressions. It can also return optional context lines around each match, making it suitable for source code and log investigation.

It restricts access to folders supplied in its configuration and uses symlink protection to help prevent traversal outside those folders. Use `list_roots` to see the directories available to the connected AI client.

Related MCP servers

Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewFilesystem Context MCP Server AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/j0hanz-filesystem-context-mcp-server?style=directory)](https://allmcps.com/mcp/j0hanz-filesystem-context-mcp-server)
HTML Embed
<a href="https://allmcps.com/mcp/j0hanz-filesystem-context-mcp-server"><img src="https://allmcps.com/api/badge/j0hanz-filesystem-context-mcp-server?style=directory" alt="Filesystem Context MCP Server on AllMCPs" /></a>