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
- Extracts all text content from PDF files
- Handles multi-page documents
- Uses
pdf-parselibrary
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
mammothlibrary
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