large-file-mcp is a server based on the Model Context Protocol (MCP), designed for intelligent processing scenarios involving large files, providing chunked reading, search, navigation, and streaming read capabilities. It was developed by willianpinho, and the project address is https://github.com/willianpinho/large-file-mcp，可通过 Install and use with npx @willianpinho/large-file-mcp.
Main capabilities Intelligent chunking: automatically determines the appropriate chunk size based on the file type, for example text files (.txt) at 500 lines per chunk, log files (.log) at 500 lines per chunk, code files (.ts, .js, .py, .java, .cpp, .go, .rs, etc.) at 300 lines per chunk, CSV files at 1000 lines per chunk, JSON files at 100 lines per chunk, XML files at 200 lines per chunk, Markdown files at 500 lines per chunk, and configuration files (.yml, .yaml, .sh, .bash) at 300 lines per chunk. Intelligent navigation: can jump to a specified line and return its surrounding context. Search: supports regular expression search and can display the number of context lines before and after matches. File analysis: provides file metadata and statistics, including line statistics, character statistics, and word count. Memory efficient: uses a streaming architecture, reading files line by line without loading the entire file into memory, and can handle files of any size. Performance optimization: built-in LRU cache, with configurable cache size (default 100MB) and expiration time (default 5 minutes), accelerating repeated access to the same file chunks or structural information. Type safe: written in TypeScript with strict typing. Cross-platform: supports Windows, macOS, and Linux.
Available tools read_large_file_chunk: reads a specified chunk of a large file, supporting intelligent chunking. Parameters include filePath (required, absolute path of the file), chunkIndex (optional, chunk index starting from 0, default 0), linesPerChunk (optional, number of lines per chunk, automatically detected if not provided), includeLineNumbers (optional, whether to include line numbers, default false). search_in_large_file: searches for a pattern in a large file with context. Parameters include pattern (required, search pattern), caseSensitive (optional, whether to be case-sensitive, default false), regex (optional, whether to use regular expressions, default false), maxResults (optional, maximum number of results, default 100), contextBefore (optional, number of context lines before a match, default 2), contextAfter (optional, number of context lines after a match, default 2). get_file_structure: Analyze the file structure and obtain complete metadata, returning file metadata, line statistics, recommended chunk size, and sample lines. navigate_to_line: Jump to the specified line and display the surrounding context. Parameters include filePath (required), lineNumber (required, a 1-based line number), contextLines (optional, the number of context lines before and after, default 5). get_file_summary: Obtain a complete statistical summary of the file, returning file metadata, line statistics, character statistics, and word count. stream_large_file: Stream-read a file in chunks, used for handling very large files. Parameters include filePath (required), chunkSize (optional, in bytes, default 64KB), startOffset (optional, starting byte offset, default 0), maxChunks (optional, maximum number of returned chunks, default 10).
Usage It can be used directly via npx, or this MCP server can be added in the Claude Code CLI for verification or removal; the server scope can be local (only the current project directory), user (global for all projects), or project (defined in .mcp.json for team sharing). In Claude Desktop, you need to edit claude_desktop_config.json: the macOS path is ~/Library/Application Support/Claude/claude_desktop_config.json, and the Windows path is %APPDATA%\Claude\claude_desktop_config.json. After editing, restart Claude Desktop. After configuration is complete, you can interact with large files using natural language. It is also compatible with Cursor and Gemini CLI, has been published to the npm and Glama.ai registries, and has been included in the community awesome-MCP directory.
Applicable Scenarios Log analysis: Process multi-GB log files for searching and navigation. Data processing: Read large CSV/JSON files in manageable chunks. Code review: Efficiently browse large codebases. System monitoring: Analyze system logs and debug output. Document analysis: Process large text documents.
Performance and Limitations The project provides a basemark test script (pnpm run benchmark), used to measure the cache hit rate under a repeatable "hot chunk" workload; under this workload, 95% has currently been measured (95 out of 100 accesses hit the cache). The cache hit rate depends on the access pattern, and there is no uniform value. The latency data for uncached readChunk() comes from scripts/benchmark.mjs, measured on an Apple M1 Pro laptop using generated test files. It is recommended to rerun the script on your own hardware to obtain your own data. The 100MB to 1GB and greater than 1GB tiers were not tested in this benchmark, but because the streaming architecture reads line by line and never loads the entire file, the time grows roughly linearly with size, and streamFile() uses AsyncGenerator, so memory usage does not grow with file size. Handling common issues: When a file is inaccessible, ensure the path is absolute and has read permission; if you encounter memory issues, you can reduce the CHUNK_SIZE environment variable, disable caching with CACHE_ENABLED=false, or use stream_large_file for very large files; if search performance is slow, you can reduce maxResults, limit the search range with startLine and endLine, and ensure caching is enabled; if the Claude Code CLI reports that the MCP server cannot be found, you can check whether it has been installed; if it is not listed, reinstall it and check the server health status.
Other Information The project welcomes contributions; you can submit an issue or pull request. The development process is to first fork the repository, create a feature branch, modify the code, ensure the build and lint succeed, and then submit a pull request; see CONTRIBUTING.md for detailed guidelines. The project is built on the Model Context Protocol SDK. Regarding pricing and charging information, the materials do not currently provide it.
