File Reader

An MCP (Model Context Protocol) server for reading and discovering files from the local filesystem.

Current capabilities

This project now provides three MCP tools:

• list_files — Lists files and folders in a given directory

  • Folders are shown with a trailing /
  • Results are sorted alphabetically
  • Access is restricted to paths under the allowed workspace

• read_file — Reads the contents of a text file

  • Returns the full file content as a string
  • Supports files inside the allowed workspace only

• search_files — Searches for files by keyword within a directory tree

  • Returns matching file paths
  • Helps quickly locate relevant files

Implementation notes

• The file access layer has been updated to use pathlib instead of os for a more modern and readable path handling approach.
• Access is still restricted to a safe allowed root for security.

Requirements

• Python 3.10+
• uv (recommended) or pip

Setup

uv sync

Running the server

uv run python src/server.py

The server uses stdio transport and is meant to be configured as an MCP server in Cursor or another MCP-compatible client.

Project structure

file_reader_mcp/
├── src/
│   ├── file_access.py  # Pathlib-based file access helpers
│   └── server.py       # MCP server exposing list_files, read_file, and search_files
├── test/
│   └── test_os.py      # Local tests for directory listing
└── pyproject.toml