MCP Smart Filesystem Server

You can use the MCP Smart Filesystem Server to explore and interact with your codebase through intelligent file paging, fast searches, and secure access. It is designed to help AI agents read large files, locate code patterns quickly, and stay within defined directory boundaries while reading only what you allow.

How to use

You interact with the server through an MCP client. The server exposes a set of capabilities to list files, read contents in paginated chunks, search code with ripgrep, and find files by name. You can run the server locally or via a container, then point your MCP client to the appropriate command or URL. Use the client to perform tasks like extracting type declarations, exploring large files in chunks, and performing targeted searches across your codebase.

How to install

Prerequisites: Node.js 22 or higher, and ripgrep installed and available in your system PATH.

Local installation steps you can follow to run the server directly on your machine.

npm install
npm run build
node dist/index.js /path/to/allowed/directory

Configuration and usage with clients

You can run the server through Docker and mount your project directory as read-only to enforce security boundaries. This lets you expose the MCP filesystem capabilities to clients without giving the client write access.

docker run -i --rm \
  -v /path/to/your/project:/workspace:ro \
  mcp-filesystem-smart

Example MCP client configuration and multiple ways to run

If you want to run the server from a container using a single command string, you can configure the client to start the server like this.

{
  "mcpServers": {
    "filesystem_smart": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/home/user/projects/myapp:/workspace:ro",
        "mcp-filesystem-smart"
      ]
    }
  }
}

Practical usage patterns

Pattern examples help you locate and read code efficiently. For example, you can search for type declarations across TS files, read around matches in large files, and read only the needed chunks to avoid context overflow.

Notes on security and access

Security boundaries are enforced by allowing access only to designated directories, preventing path traversal, and avoiding symlink attacks. When using Docker, mount volumes as read-only to enforce safety.

Available tools

list_directory

List directory contents with metadata including files, directories, sizes, line counts, and summary statistics.

read_file

Read file contents with automatic pagination for large files. Returns the first 500 lines for files over 500 lines with hasMore and nextStartLine to fetch the next chunk.

search_code

Search code patterns using ripgrep with options for path, file patterns, case sensitivity, context lines, max results, and more.

search_in_file

Search within a specific file, similar to Ctrl+F with optional context lines.

find_files

Find files by name pattern using flexible glob patterns.

get_file_info

Get file metadata such as size, line count, language, binary status, and reading strategy for large files.

list_allowed_directories

Show the directories that are accessible under security boundaries.