willianpinho/large-file-mcp

MCP server for intelligent handling of large files — smart chunking, search, navigation, and streaming.
> 🔗 **Live Demo / Landing Page** — install with npx @willianpinho/large-file-mcp
>
> 📚 **Full Documentation** | API Reference | Examples
Features
- **Smart Chunking** - Automatically determines optimal chunk size based on file type
- **Intelligent Navigation** - Jump to specific lines with surrounding context
- **Powerful Search** - Regex support with context lines before/after matches
- **File Analysis** - Comprehensive metadata and statistical analysis
- **Memory Efficient** - Stream files of any size without loading into memory
- **Performance Optimized** - Built-in LRU caching for frequently accessed chunks
- **Type Safe** - Written in TypeScript with strict typing
- **Cross-Platform** - Works on Windows, macOS, and Linux
Installation
Or use directly with npx:
Quick Start
Claude Code CLI
Add the MCP server using the CLI:
**Verify installation:**
**Remove if needed:**
**MCP Scopes:**
- local - Available only in the current project directory
- user - Available globally for all projects
- project - Defined in .mcp.json for team sharing
Claude Desktop
Add to your claude_desktop_config.json:
**Config file locations:**
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Restart Claude Desktop after editing.
Other AI Platforms
**Gemini:**
Usage
Once configured, you can use natural language to interact with large files:
Available Tools
read_large_file_chunk
Read a specific chunk of a large file with intelligent chunking.
**Parameters:**
- filePath (required): Absolute path to the file
- chunkIndex (optional): Zero-based chunk index (default: 0)
- linesPerChunk (optional): Lines per chunk (auto-detected if not provided)
- includeLineNumbers (optional): Include line numbers (default: false)
**Example:**
search_in_large_file
Search for patterns in large files with context.
**Parameters:**
- filePath (required): Absolute path to the file
- pattern (required): Search pattern
- caseSensitive (optional): Case sensitive search (default: false)
- regex (optional): Use regex pattern (default: false)
- maxResults (optional): Maximum results (default: 100)
- contextBefore (optional): Context lines before match (default: 2)
- contextAfter (optional): Context lines after match (default: 2)
**Example:**
get_file_structure
Analyze file structure and get comprehensive metadata.
**Parameters:**
- filePath (required): Absolute path to the file
**Returns:** File metadata, line statistics, recommended chunk size, and sample lines.
navigate_to_line
Jump to a specific line with surrounding context.
**Parameters:**
- filePath (required): Absolute path to the file
- lineNumber (required): Line number to navigate to (1-indexed)
- contextLines (optional): Context lines before/after (default: 5)
get_file_summary
Get comprehensive statistical summary of a file.
**Parameters:**
- filePath (required): Absolute path to the file
**Returns:** File metadata, line statistics, character statistics, and word count.
stream_large_file
Stream a file in chunks for processing very large files.
**Parameters:**
- filePath (required): Absolute path to the file
- chunkSize (optional): Chunk size in bytes (default: 64KB)
- startOffset (optional): Starting byte offset (default: 0)
- maxChunks (optional): Maximum chunks to return (default: 10)
Supported File Types
The server intelligently detects and optimizes for:
- Text files (.txt) - 500 lines/chunk