@mcp-monorepo/file-browser

MCP server for file system browsing and manipulation (search, ls, tree, grep, open, write, move, mkdir)

This package provides a comprehensive set of tools for an AI agent to interact with a local file system. It enables operations such as reading, writing, patching, and moving files, as well as creating, listing, and removing directories. For security, all operations are strictly sandboxed within a user-defined working directory.

Key Features

• Secure Sandboxing: All file system access is restricted to the directory specified by the WORKING_DIR environment variable, preventing unintended access to other parts of the system.
• Comprehensive File Operations: Includes tools for creating, reading, writing, patching, moving, and deleting files and directories.
• Advanced Search & Replace: A powerful find-or-replace tool that supports multi-line, case-sensitive regular expressions across multiple files.
• Fuzzy Context Patching: The patch-file tool can intelligently apply changes to a file using approximate line numbers and context matching, making it resilient to minor code shifts.
• Rich Directory Traversal: Provides both a flat list-directory view and a nested tree-directory view, with options for filtering by depth and regular expressions.
• .gitignore Aware: Directory traversal tools automatically respect .gitignore files, ensuring that ignored files and folders are excluded from results.

Usage

You can run this MCP server directly using npx for local testing:

npx @mcp-monorepo/file-browser@latest

To integrate this server with a compatible AI model (like Claude), provide the following MCP server configuration:

{
  "mcpServers": {
    "file-browser": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-monorepo/file-browser"
      ],
      "env": {
        "WORKING_DIR": "<Your WORKING_DIR Here>"
      }
    }
  }
}

Environment Variables

| Variable | Description | Default | | :--- | :--- | :--- | | WORKING_DIR | The absolute path to the root directory that the file browser is sandboxed to. All file operations will be constrained within this path. | <required> |

Tools

open-file

Open File - Opens a file by its relative filepath and returns its content.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | filepath | string | |

write-file

Write File - Create or completely overwrite a file with new content. Creates parent directories if they don't exist.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | filepath | string | | | content | string | Content to write to the file |

move-path

Move Path - Moves files or directories to new locations. Each source must exist, and each target must not.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | paths | array of object | |

list-directory

List Directory Contents - Lists the contents of a directory with details.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | dirpath | string | Relative path to the directory. Defaults to current working directory. |

tree-directory

Tree Directory Contents - Generates a nested JSON representation with optional filtering of the directory contents.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | dirpath | string | Relative path to the tree root directory. Defaults to current working directory. | | depth | number | Maximum depth to traverse | | regexp | string | Only relative paths in unix style (e.g. "dir/to/file.txt") matching this regexp (e.g. "to/.*.txt") will be returned. |

mk-dir

Make Directory - Creates a directory and all necessary parent directories recursively.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | dirpath | string | |

remove-file

Remove File - Removes a file or directory. For directories, removes recursively including all contents.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | filepath | string | |

find-or-replace

Find or Replace Text in Files - Search for text patterns in files with optional replacement. Supports multi-line matches and provides context.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | dirpath | string | Relative path to search directory. Defaults to current working directory. | | fileRegexp | string | Regexp to filter file paths (e.g. ".*.ts$" for TypeScript files). | | searchRegexp | string | Regexp pattern to search for in file contents. Can span multiple lines. The flags "gms" will be used. | | replaceString | string | Replacement string. Use $1, $2, etc. for capture groups. If provided, performs replacement instead of showing matches. |

patch-file

Patch File - Apply a patch to a file by replacing content between approximate start and end line numbers with context matching. Provide at least one line of unmodified content before and after the change.

Input Schema

| Property | Type | Description | | :--- | :--- | :--- | | path | string | | | patch | string | | | approxStartLine | integer | Approximate start line number of the patch | | approxEndLine | integer | Approximate end line number of the patch. Must be equal or greater than start line. |

Other MCP Servers

This monorepo contains several other MCP server packages available on npm. Each provides a distinct set of tools for use with the Model Context Protocol.

• @mcp-monorepo/confluence: MCP server for Confluence API tools
• @mcp-monorepo/ics: MCP server for calendar tools using ICS/ical feeds
• @mcp-monorepo/jira: MCP server for Jira tools (JQL, issue management, etc.).
• @mcp-monorepo/location: MCP server for location-based tools using IP address lookup
• @mcp-monorepo/mail: MCP server for mail tools (fetch, read, search, mark as seen).
• @mcp-monorepo/notion-query: MCP server for querying Notion data sources.
• @mcp-monorepo/npm: MCP server for npm command tools (run scripts, install packages, list scripts)
• @mcp-monorepo/slack: Slack MCP to access workspace without bot account or app
• @mcp-monorepo/weather: Weather MCP tools (geocoding, weather-by-coords) for ModelContextProtocol.

Recent Changes

Version 1.1.4

• fd22b00: Fixed yarn versioning during publish

Version 1.1.3

• Updated dependencies [7929a55]

Version 1.1.2

• 75e8973: migrate monorepo to yarn 4, update CI/husky/scripts and run-on-changed, add yarnrc and packageManager, switch internal deps to workspace:* and simplify bin fields

Authors

• The MCP Monorepo Team

License

This project is licensed under the AGPL-3.0-only License. See the LICENSE file for details.