j0hanz/filesystem-context-mcp-server

Filesystem Context MCP Server

A secure, read-only MCP server for filesystem scanning, searching, and analysis with comprehensive security validation.

One-Click Install

✨ Features

🎯 When to Use

🚀 Quick Start

NPX (Recommended - Zero Config)

# Works in current directory automatically!
npx -y @j0hanz/filesystem-context-mcp@latest

Or specify directories explicitly:

npx -y @j0hanz/filesystem-context-mcp@latest /path/to/your/project

VS Code (with workspace folder)

Add to your VS Code settings (.vscode/mcp.json):

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

Tip: ${workspaceFolder} automatically uses your current VS Code workspace. You can also omit it and the server will use its current working directory.

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

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

Note: Claude Desktop will use the current working directory automatically. No path arguments needed!

📦 Installation

NPX (No Installation)

npx -y @j0hanz/filesystem-context-mcp@latest /path/to/dir1 /path/to/dir2

Global Installation

npm install -g @j0hanz/filesystem-context-mcp
filesystem-context-mcp /path/to/your/project

From Source

git clone https://github.com/j0hanz/filesystem-context-mcp-server.git
cd filesystem-context-mcp-server
npm install
npm run build
node dist/index.js /path/to/your/project

⚙️ Configuration

Directory Resolution (Priority Order)

The server determines which directories to access in this order:

1. CLI Arguments - Explicitly passed paths take highest priority
2. MCP Roots Protocol - Directories provided by the MCP client
3. Current Working Directory - Automatic fallback for plug-and-play experience

This means you can run the server with zero configuration and it will work!

Command Line Arguments

Optionally specify one or more directory paths as arguments:

filesystem-context-mcp /home/user/project /home/user/docs

MCP Roots Protocol

If no CLI arguments are provided, the server will use the MCP Roots protocol to receive allowed directories from the client (if supported).

Zero-Config Mode

If neither CLI arguments nor MCP Roots provide directories, the server automatically uses the current working directory. This makes it truly plug-and-play!

Environment Variables

All configuration values have sensible defaults and are optional. Only configure if you need to tune performance or resource usage.

💡 Tip: See for detailed environment variable usage examples, configuration profiles, and best practices for different use cases.

🔧 Tools

list_allowed_directories

List all directories that this server is allowed to access.

Returns: Array of allowed directory paths.

list_directory

List contents of a directory with optional recursive listing.

Returns: List of entries with name, type, size, and modified date.

search_files

Search for files (not directories) using glob patterns.

Returns: List of matching files with path, type, size, and modified date.

Example:

{
  "path": "/project",
  "pattern": "**/*.ts",
  "excludePatterns": ["node_modules/**", "dist/**"]
}

read_file

Read the contents of a text file.

Note: Cannot specify both head and tail simultaneously. Use lineStart/lineEnd for range reading.

Returns: File contents as text.

read_multiple_files

Read multiple files in parallel for efficient batch operations.

Returns: Array of file contents with individual success/error status.

get_multiple_file_info

Get metadata for multiple files/directories in parallel.

Returns: Array of file info (name, path, type, size, timestamps, permissions, mimeType) with individual success/error status, plus summary.

compute_checksums

Compute cryptographic checksums for files using memory-efficient streaming.

Returns: Array of checksums with file sizes, plus summary (total, succeeded, failed).

Use cases:

• Verify file integrity after transfers
• Detect duplicate files by comparing hashes
• Generate checksums for release artifacts

Note: Use read_file for single files with line ranges (lineStart/lineEnd). Use read_multiple_files for batch operations with head/tail parameters. The batch API does not support line ranges per file.

Returns: Array of results with content or error for each file.

get_file_info

Get detailed metadata about a file or directory.

Returns: Metadata including name, type, size, created/modified/accessed timestamps, permissions, MIME type, and symlink target (if applicable).

search_content

Search for text content within files using regular expressions.

Returns: Matching lines with file path, line number, content, and optional context.

Example:

{
  "path": "/project/src",
  "pattern": "TODO|FIXME",
  "filePattern": "**/*.ts",
  "contextLines": 2
}

search_definitions

Find code definitions (classes, functions, interfaces, types, enums, variables) in TypeScript/JavaScript files without manual regex construction.

Returns: List of definitions with name, type (class/function/interface/type/enum/variable), file path, line number, exported status, and code preview.

Use cases:

• Find by name: Search for a specific definition like UserService
• Discovery mode: Find all definitions of a type (e.g., all interfaces)
• Combined: Find definitions matching a name pattern and type

Examples:

{
  "path": "/project/src",
  "name": "UserService"
}

{
  "path": "/project/src",
  "type": "interface"
}

{
  "path": "/project/src",
  "name": "Handler",
  "type": "class"
}

analyze_directory

Analyze a directory structure and return statistics.

Returns: Statistics including total files/directories, total size, file type distribution, largest files, and recently modified files.

directory_tree

Get a JSON tree structure of a directory, optimized for AI parsing.

Returns: Hierarchical tree structure with file/directory nodes.

read_media_file

Read a binary/media file and return it as base64-encoded data.

Supported formats: Images (PNG, JPG, GIF, WebP, SVG, etc.), Audio (MP3, WAV, FLAC, etc.), Video (MP4, WebM, etc.), Fonts (TTF, WOFF, etc.), PDFs, and more.

Returns: Base64-encoded data with MIME type and size.

🔌 Client Configuration

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

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

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

[mcp_servers.filesystem-context]
command = "npx"
args = ["-y", "@j0hanz/filesystem-context-mcp@latest"]

[mcp_servers.filesystem-context]
command = "npx"
args = ["-y", "@j0hanz/filesystem-context-mcp@latest", "/path/to/your/project"]

[mcp_servers.filesystem-context]
command = "npx"
args = ["-y", "@j0hanz/filesystem-context-mcp@latest", "/path/to/project1", "/path/to/project2"]

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

🔒 Security

This server implements multiple layers of security:

Security Model

┌─────────────────────────────────────────────────────────┐
│                    MCP Client                           │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│            Filesystem Context MCP Server                │
│  ┌───────────────────────────────────────────────────┐  │
│  │              Path Validation Layer                │  │
│  │  • Normalize paths                                │  │
│  │  • Check against allowed directories              │  │
│  │  • Resolve and validate symlinks                  │  │
│  │  • Block traversal attempts                       │  │
│  └───────────────────────────────────────────────────┘  │
│                         │                               │
│                         ▼                               │
│  ┌───────────────────────────────────────────────────┐  │
│  │            Read-Only File Operations              │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              Allowed Directories Only                   │
│  /home/user/project  ✅                                 │
│  /home/user/docs     ✅                                 │
│  /etc/passwd         ❌ (blocked)                       │
│  ../../../etc        ❌ (blocked)                       │
└─────────────────────────────────────────────────────────┘

🛠️ Development

Prerequisites

• Node.js >= 20.0.0
• npm

Scripts

Project Structure

src/
├── index.ts              # Entry point, CLI argument parsing
├── server.ts             # MCP server setup, roots protocol handling
├── instructions.md       # AI instructions for tool usage (bundled with dist)
├── config/
│   └── types.ts          # Shared TypeScript types
├── lib/
│   ├── constants.ts      # Configuration constants and limits
│   ├── errors.ts         # Error handling utilities
│   ├── file-operations.ts# Core filesystem operations (exports)
│   ├── path-utils.ts     # Path manipulation utilities
│   ├── path-validation.ts# Security: path validation layer
│   ├── fs-helpers.ts     # Low-level filesystem helpers (exports)
│   ├── file-operations/  # Core filesystem operations
│   │   ├── analyze-directory.ts
│   │   ├── directory-helpers.ts
│   │   ├── directory-tree.ts
│   │   ├── file-info.ts
│   │   ├── list-directory.ts
│   │   ├── pattern-validator.ts
│   │   ├── read-media-file.ts
│   │   ├── read-multiple-files.ts
│   │   ├── search-content.ts
│   │   ├── search-definitions.ts
│   │   ├── search-files.ts
│   │   └── sorting.ts
│   ├── fs-helpers/       # Low-level filesystem helpers
│   │   ├── binary-detect.ts
│   │   ├── concurrency.ts
│   │   ├── fs-utils.ts
│   │   ├── readers.ts
│   │   └── readers/      # File reading utilities
│   │       ├── head-file.ts
│   │       ├── line-range.ts
│   │       ├── read-file.ts
│   │       ├── tail-file.ts
│   │       └── utf8.ts
│   └── path-validation/  # Security: path validation
│       ├── allowed-directories.ts
│       ├── errors.ts
│       ├── roots.ts
│       └── validators.ts
├── schemas/
│   ├── common.ts         # Shared Zod schemas
│   ├── input-helpers.ts  # Input validation helpers
│   ├── inputs.ts         # Input validation schemas
│   ├── output-helpers.ts # Output formatting helpers
│   ├── outputs.ts        # Output validation schemas
│   └── index.ts          # Schema exports
├── tools/
│   ├── analyze-directory.ts
│   ├── directory-tree.ts
│   ├── get-file-info.ts
│   ├── list-allowed-dirs.ts
│   ├── list-directory.ts
│   ├── read-file.ts
│   ├── read-media-file.ts
│   ├── read-multiple-files.ts
│   ├── search-content.ts
│   ├── search-definitions.ts
│   ├── search-files.ts
│   ├── tool-response.ts  # Tool response formatting
│   └── index.ts          # Tool registration
└── __tests__/            # Test files
    ├── lib/
    │   ├── errors.test.ts
    │   ├── file-operations.test.ts
    │   ├── fs-helpers.test.ts
    │   └── path-validation.test.ts
    ├── schemas/
    │   └── validators.test.ts
    └── security/
        └── filesystem-boundary.test.ts

Testing with MCP Inspector

npm run inspector

This launches the MCP Inspector for interactive testing of all tools.

❓ Troubleshooting

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run tests and linting (npm run lint && npm run test)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

Code Style

• Use TypeScript with strict mode
• Follow ESLint configuration
• Use Prettier for formatting
• Write tests for new features