Skip to main content
Glama
j0hanz

FS Context MCP Server

by j0hanz
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

Filesystem MCP

npm version License Node.js Version Docker Image

Install in VS Code Install in VS Code Insiders Install in Claude Desktop Install in Cursor

MCP Server that enables LLMs to interact with the local filesystem. Provides tools for navigation, file management, searching, and analysis, all within a secure, allowed set of directories. Ideal for agents needing to read/write files, explore directory structures, or perform file operations as part of their tasks.

Key Features

  • Navigation: List directories (ls), view trees (tree), and discover workspace roots (roots).

  • File Management: Create (mkdir), write (write), edit (edit), move (mv), and delete (rm) files/directories.

  • Search: Find files by glob pattern (find) or search content using regex (grep).

  • Analysis: Inspect metadata (stat), calculate hashes (calculate_hash), and compare files (diff_files).

  • Batch Operations: Read multiple files (read_many) or replace text across many files (search_and_replace).

  • Security: Strictly scoped to allowed directories provided at startup.

Tech Stack

  • Runtime: Node.js >= 24

  • Language: TypeScript

  • SDK: @modelcontextprotocol/sdk

  • Libraries: zod, commander, re2, diff

Repository Structure

. ├── src/ │ ├── index.ts # Entry point │ ├── server.ts # MCP Server implementation │ ├── tools/ # Individual tool implementations │ └── lib/ # Shared utilities ├── assets/ # Images and static resources ├── scripts/ # Build and maintenance scripts └── package.json

Requirements

  • Node.js >= 24

Quickstart

Run directly with npx:

npx -y @j0hanz/filesystem-mcp@latest "C:\path\to\allowed\directory"

Installation

NPX (Recommended)

npx -y @j0hanz/filesystem-mcp@latest [options] [directories...]

Docker

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

Mount host directories as volumes to /projects/ and pass the container paths as arguments.

From Source

  1. Clone the repository

  2. Install dependencies:

    npm ci

  3. Build the project:

    npm run build

  4. Run:

    node dist/index.js [options] [directories...]

Configuration

The server requires specifying allowed directories via command-line arguments.

Arguments

Argument

Description

[allowedDirs...]

Positional arguments specifying the root directories the server can access.

Options

Option

Description

--allow-cwd

Allow the current working directory as an additional root.

-v, --version

Display server version.

-h, --help

Display command help.

Usage

Stdio Transport

The server communicates via stdio. Ensure your MCP client is configured to run the server command and capture standard input/output.

MCP Surface

Tools

Tool

Description

Key Parameters

roots

List allowed workspace roots

None

ls

List directory contents

path, includeHidden

find

Find files by glob pattern

pattern, path, maxDepth

tree

Generate directory tree

path, maxDepth

read

Read file content

path, head

read_many

Read multiple files

paths

grep

Search file content (regex/literal)

pattern, path, isRegex

stat

Get file metadata

path

stat_many

Get metadata for multiple files

paths

calculate_hash

Calculate SHA-256 hash

path

mkdir

Create directory (recursive)

path

write

Write file (create/overwrite)

path, content

edit

Edit file (string replacement)

path, edits

mv

Move or rename file/directory

source, destination

rm

Delete file or directory

path, recursive

diff_files

Generate unified diff

original, modified

apply_patch

Apply unified patch

path, patch

search_and_replace

Search & replace across files

filePattern, searchPattern, replacement

Resources

URI Pattern

Description

internal://instructions

Usage guidance and documentation

filesystem-mcp://result/{id}

Ephemeral cached tool output (for large results)

Prompts

Prompt

Description

get-help

Returns usage instructions for the server

Client Configuration Examples

Add to your claude_desktop_config.json:

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

Add to your .cursor/mcp.json or configure via UI:

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

Add to your .vscode/mcp.json:

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

Use the Docker image with any MCP client that supports stdio transport:

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

Add to your configuration:

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

Security

  • Path Restrictions: All file operations are strictly validated against the allowed root directories provided at startup.

  • Path Validation: Uses isPathWithinDirectories to prevent path traversal attacks.

  • Hidden Files: Hidden files (starting with .) are excluded by default in listings and searches unless explicitly requested.

Development Workflow

  1. Install Dependencies:

    npm install

  2. Development Mode (watch):

    npm run dev

  3. Run Locally:

    npm start -- --allow-cwd

  4. Test:

    npm run test

  5. Lint & Format:

    npm run lint npm run format

License

MIT

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/j0hanz/fs-context-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server