Skip to main content
Glama
j0hanz

FS Context MCP Server

by j0hanz
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

FS Context MCP Server

npm version License Node.js TypeScript MCP SDK

Install with NPX in VS Code Install with NPX in VS Code Insiders

Read-only Model Context Protocol (MCP) server for secure filesystem exploration, searching, and analysis.

Overview

This server enables AI assistants to navigate your filesystem through a set of read-only tools. It provides capabilities to explore directory structures, find files using glob patterns, search file contents with grep, read files (including batch operations), and access file metadata—all restricted to explicitly approved directories.

Key Features

  • Read-Only Security: No write, delete, or modify permissions.

  • Allowed Roots: Access is strictly limited to configured directories.

  • Directory Exploration: List contents (ls) and visualize structures (tree).

  • File Search: Find files by name or pattern (find) and search content (grep).

  • File Reading: Read single (read) or multiple (read_many) files with line-range support.

  • Metadata: Retrieve file stats (stat, stat_many) including size and timestamps.

  • Large File Handling: Automatic truncation and pagination for large outputs.

  • Ignore Support: Respects .gitignore and common ignore patterns by default.

Tech Stack

  • Runtime: Node.js >= 22.19.8

  • Language: TypeScript 5.9.3

  • MCP SDK: @modelcontextprotocol/sdk 1.25.3

  • Libraries: zod (validation), re2 (safe regex), ignore (filtering)

Repository Structure

src/ ├── tools/ # Tool implementations (read, find, grep, etc.) ├── lib/ # Core logic (filesystem, validation, errors) ├── index.ts # CLI entrypoint ├── server.ts # MCP server setup and roots management ├── tools.ts # Tool registration ├── resources.ts # Resource registration ├── schemas.ts # Zod schemas for inputs/outputs └── config.ts # Shared configuration types

Requirements

  • Node.js >= 22.19.8

Quickstart

Use npx to run the server directly.

npx -y @j0hanz/fs-context-mcp@latest --allow-cwd

VS Code Configuration

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

Installation

NPX (Recommended)

npx -y @j0hanz/fs-context-mcp@latest /path/to/directory

Global Installation

npm install -g @j0hanz/fs-context-mcp fs-context-mcp /path/to/directory

From Source

  1. Clone the repository:

    git clone https://github.com/j0hanz/fs-context-mcp-server.git cd fs-context-mcp-server

  2. Install dependencies:

    npm ci

  3. Build the project:

    npm run build

  4. Run the server:

    node dist/index.js /path/to/directory

Configuration

Runtime Modes

This server runs over stdio by default.

CLI Arguments

Argument

Description

[paths...]

List of allowed root directories.

--allow-cwd

Add the current working directory to allowed roots.

Environment Variables

Variable

Default

Description

MAX_FILE_SIZE

10MB

Max file size for read operations.

MAX_READ_MANY_TOTAL_SIZE

512KB

Max combined size for read_many.

MAX_SEARCH_SIZE

1MB

Max file size for grep.

DEFAULT_SEARCH_TIMEOUT

30000

Timeout (ms) for search/list operations.

FS_CONTEXT_SEARCH_WORKERS

min(cpu, 8)

Number of worker threads for search.

FS_CONTEXT_ALLOW_SENSITIVE

false

Allow reading sensitive files (disables denylist).

FS_CONTEXT_DENYLIST

(empty)

Additional comma-separated glob patterns to block.

FS_CONTEXT_ALLOWLIST

(empty)

Comma-separated globs to allow despite denylist.

FS_CONTEXT_TOOL_LOG_ERRORS

false

Log tool failures to stderr.

MCP Surface

Tools

roots

List the workspace roots this server can access.

  • Returns: List of allowed directory paths.

ls

List the immediate contents of a directory.

Parameter

Type

Required

Default

Description

path

string

No

(root)

Directory path to list.

includeHidden

boolean

No

false

Include hidden files.

includeIgnored

boolean

No

false

Include ignored directories (node_modules, etc).

find

Find files by glob pattern.

Parameter

Type

Required

Default

Description

pattern

string

Yes

-

Glob pattern (e.g., **/*.ts).

path

string

No

(root)

Base directory to search from.

includeIgnored

boolean

No

false

Include ignored directories.

maxResults

number

No

100

Maximum matches to return.

tree

Render a directory tree.

Parameter

Type

Required

Default

Description

path

string

No

(root)

Base directory to render.

maxDepth

number

No

5

Maximum recursion depth.

maxEntries

number

No

1000

Max entries before truncating.

includeHidden

boolean

No

false

Include hidden files.

includeIgnored

boolean

No

false

Include ignored directories.

read

Read the text contents of a file.

Parameter

Type

Required

Default

Description

path

string

Yes

-

Path to the file.

head

number

No

-

Read only first N lines.

startLine

number

No

-

1-based start line.

endLine

number

No

-

1-based end line.

read_many

Read multiple text files in a single request.

Parameter

Type

Required

Default

Description

paths

string[]

Yes

-

Array of file paths to read (max 100).

head

number

No

-

Read only first N lines of each file.

startLine

number

No

-

1-based start line per file.

endLine

number

No

-

1-based end line per file.

stat

Get metadata for a file or directory.

Parameter

Type

Required

Default

Description

path

string

Yes

-

Path to file or directory.

stat_many

Get metadata for multiple files/directories.

Parameter

Type

Required

Default

Description

paths

string[]

Yes

-

Array of paths to query.

grep

Search for text within file contents.

Parameter

Type

Required

Default

Description

pattern

string

Yes

-

Text pattern to search for.

path

string

No

(root)

Base directory or file to search.

includeHidden

boolean

No

false

Include hidden files.

Resources

Pattern

Description

internal://instructions

Usage guidance and server instructions.

fs-context://result/{id}

Access to cached large tool outputs.

Client Configuration Examples

Add to .vscode/mcp.json:

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

Add to claude_desktop_config.json:

{ "mcpServers": { "fs-context": { "command": "npx", "args": [ "-y", "@j0hanz/fs-context-mcp@latest", "/absolute/path/to/project" ] } } }

Add to Cursor's MCP configuration:

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

Add to Windsurf's MCP configuration:

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

Security

  • Read-Only: This server is designed to be read-only. It provides no tools for writing or modifying files.

  • Path Validation: All file access is validated against the allowed root directories.

  • Path Traversal: Attempts to access files outside allowed roots using .. are blocked.

  • Symlinks: Symlinks resolving outside allowed roots are blocked.

  • Sensitive Files: Common sensitive files (e.g., .env, .ssh/id_rsa) are denied by default unless explicitly allowed via configuration.

  • Stdio: The server communicates via stdio. Ensure your client does not pipe untrusted data into the server's input.

Development Workflow

  1. Install dependencies: npm ci

  2. Run in dev mode: npm run dev (watches for changes)

  3. Build: npm run build

  4. Test: npm test

  5. Lint: npm run lint

Troubleshooting

  • Access Denied: Ensure the directory is included in the CLI arguments or client roots configuration.

  • File Too Large: Large files are truncated. Use the head parameter or startLine/endLine to read specific sections, or follow the resource URI provided in the tool output.

  • Timeout: Complex searches (grep or find) may timeout on large codebases. Try narrowing the search path.

License

This project is licensed under the MIT License - see the LICENSE file for details.

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