Skip to main content
Glama
MCP Local File Reader
by yryuu

MCP Local File Reader

A Model Context Protocol (MCP) server that provides comprehensive file system operations with support for multiple document formats. Works with Claude Desktop and other MCP-compatible AI tools.

Features

  • πŸ“ File System Operations: List directories, read files, get file metadata

  • πŸ” Search Capabilities: Grep-like content search and file name pattern matching

  • πŸ“„ Multi-Format Support:

    • PDF text extraction

    • Excel (.xlsx, .xls) with sheet listing and per-sheet reading

    • Word documents (.docx)

    • PowerPoint presentations (.pptx)

    • CSV files

    • Text files with automatic encoding detection (Shift-JIS/UTF-8)

  • 🌐 Character Encoding: Automatic detection and conversion of Shift-JIS and UTF-8

  • πŸ”’ Security: Path validation to prevent access outside designated root directory

Related MCP server: MCP File Browser Server

Installation

No installation needed! Just configure Claude Desktop to use npx:

{
  "mcpServers": {
    "localfile-reader": {
      "command": "npx",
      "args": [
        "-y",
        "github:yryuu/mcp-localfile-all-read"
      ],
      "env": {
        "MCP_ROOT_PATH": "/path/to/your/directory"
      }
    }
  }
}

Local Installation

npx github:yryuu/mcp-localfile-all-read

Configuration

Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the server configuration:

{
  "mcpServers": {
    "localfile-reader": {
      "command": "npx",
      "args": ["-y", "github:yryuu/mcp-localfile-all-read"],
      "env": {
        "MCP_ROOT_PATH": "/Users/yourname/Documents"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "localfile-reader": {
      "command": "mcp-localfile-reader",
      "env": {
        "MCP_ROOT_PATH": "/Users/yourname/Documents"
      }
    }
  }
}

Environment Variables

  • MCP_ROOT_PATH: Root directory for file access (defaults to current working directory)

Windows Example:

{
  "env": {
    "MCP_ROOT_PATH": "C:\\Users\\YourName\\Documents"
  }
}

macOS/Linux Example:

{
  "env": {
    "MCP_ROOT_PATH": "/Users/yourname/Documents"
  }
}

Note: On Windows, use double backslashes (\\) or forward slashes (/) in paths. See WINDOWS.md for detailed Windows compatibility information.

Available Tools

list_directory

List contents of a directory.

Parameters:

  • path (string): Relative path from root directory. Use "." for root.

Example:

List the contents of the current directory

read_file

Read file content with automatic format detection.

Parameters:

  • path (string): Relative path to the file.

Supported formats:

  • Text files (.txt, .md, .json, .xml, etc.)

  • PDF (.pdf)

  • Excel (.xlsx, .xls)

  • Word (.docx)

  • PowerPoint (.pptx)

  • CSV (.csv)

Example:

Read the contents of report.pdf

get_file_info

Get metadata about a file or directory.

Parameters:

  • path (string): Relative path to the file or directory.

Example:

Get information about data.xlsx

search_content

Search for text patterns in files. Returns a list of file paths that contain the pattern.

Parameters:

  • path (string): Relative path to search in.

  • pattern (string): Text pattern or regex to search for.

  • max_results (number): Optional. Maximum number of files to return (default: 1000).

  • file_pattern (string, optional): Filter files by name pattern.

  • case_sensitive (boolean, optional): Case sensitive search. Default: false.

Example:

Search for "TODO" in all JavaScript files

find_files

Find files by name pattern.

Parameters:

  • path (string): Relative path to search in.

  • name_pattern (string): File name pattern or regex.

  • case_sensitive (boolean, optional): Case sensitive search. Default: false.

Example:

Find all PDF files in the current directory

list_excel_sheets

List all sheet names in an Excel file.

Parameters:

  • path (string): Relative path to the Excel file.

Example:

List all sheets in budget.xlsx

read_excel_sheet

Read a specific sheet from an Excel file.

Parameters:

  • path (string): Relative path to the Excel file.

  • sheet_name (string): Name of the sheet to read.

Example:

Read the "Sales" sheet from budget.xlsx

Development

Setup

git clone https://github.com/yryuu/mcp-localfile-all-read.git
cd mcp-localfile-all-read
npm install

Build

npm run build

Testing Locally

Use the MCP Inspector to test the server:

npx @modelcontextprotocol/inspector node dist/index.js

Or set the root path:

MCP_ROOT_PATH=/path/to/test/directory npx @modelcontextprotocol/inspector node dist/index.js

Usage Examples

With Claude Desktop

After configuration, you can ask Claude:

  • "List all files in the current directory"

  • "Read the contents of report.pdf"

  • "Search for 'error' in all log files"

  • "Find all Excel files"

  • "List the sheets in budget.xlsx and read the Sales sheet"

  • "Read the Word document proposal.docx"

Programmatic Usage

import { Server } from '@modelcontextprotocol/sdk/server/index.js';

// The server runs on stdio transport
// See src/index.ts for implementation details

File Format Support Details

PDF

  • Extracts all text content from PDF files

  • Handles multi-page documents

  • Uses pdf-parse library

Excel

  • Supports .xlsx and .xls formats

  • List all sheet names

  • Read specific sheets or all sheets

  • Returns data as JSON arrays

Word

  • Supports .docx format

  • Extracts plain text content

  • Uses mammoth library

PowerPoint

  • Supports .pptx format

  • Extracts text from all slides

  • Returns slide-by-slide content

CSV

  • Automatic delimiter detection

  • Character encoding detection (Shift-JIS/UTF-8)

  • Returns structured JSON data

Text Files

  • Automatic character encoding detection

  • Supports Shift-JIS and UTF-8

  • Handles various text-based formats

Security

  • Path validation prevents access outside the configured root directory

  • All paths are resolved and validated before file operations

  • Error handling for permission issues and invalid paths

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Author

yryuu

Repository

https://github.com/yryuu/mcp-localfile-all-read

Available Tools

7 tools
find_filesA

Find files by name pattern. Returns list of matching file paths. Recursively searches all subdirectories by default.

Inputs: path (required), name_pattern (required), case_sensitive.

get_file_infoB

Get metadata about a file or directory including size, type, and modification date.

Inputs: path (required).

list_directoryB

List contents of a directory. Returns file and directory information including names, types, sizes, and modification dates.

Inputs: path (required).

list_excel_sheetsB

List all sheet names in an Excel file (.xlsx or .xls).

Inputs: path (required).

read_excel_sheetB

Read a specific sheet from an Excel file. Returns data as JSON.

Inputs: path (required), sheet_name (required).

read_fileA

Read file content with automatic format detection. Supports text files, PDF, Excel, Word, PowerPoint, and CSV with automatic encoding detection (Shift-JIS/UTF-8).

Inputs: path (required).

search_contentA

Search for text pattern in files (grep-like functionality). Returns list of unique file paths containing the pattern. Recursively searches all subdirectories by default. Automatically skips node_modules, .git, dist, build directories and binary files for performance.

Inputs: path (required), pattern (required), file_pattern, case_sensitive, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between find_files and search_content, as both involve searching files, which could cause minor confusion. However, their descriptions clarify that find_files searches by name pattern while search_content searches by text pattern, helping to differentiate them.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., find_files, get_file_info, list_directory), with no deviations in style or convention. This predictability makes the tool set easy to navigate and understand.

    Tool Count5/5

    With 7 tools, the count is well-scoped for a local file reader server, covering essential operations like listing, reading, and searching files. Each tool serves a clear purpose without redundancy, making the set appropriately sized for the domain.

    Completeness4/5

    The tool set covers core file operations including listing, reading, and searching, with good support for various file formats. A minor gap is the lack of write or update operations, but this is reasonable for a read-focused server, and agents can still perform common workflows without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides secure file system operations for AI assistants including directory listing, file reading/writing, deletion, searching, and copying. Features safety controls like path validation, permission checks, and file size limits.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Large Language Models to safely browse and interact with local file systems through secure directory listing, file reading, and content search capabilities. Built with comprehensive security controls and high-performance handling of large directories and files.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables intelligent file searching in local directories using natural language queries. Supports searching by file type, filename patterns, and content across multiple formats including PDF, Word, Excel, and text files with AI-powered relevance scoring.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to read, search, and analyze local file systems with tools for reading file contents, listing directories, searching by patterns, and analyzing folder structures for context-aware queries.
      MIT