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

Installation

Using npx (Recommended)

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