largefile
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@largefile search for ERROR in /var/log/app.log"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Largefile MCP Server
Navigate, search, and edit large codebases, logs, and data files that exceed AI context limits.
Why Largefile?
Go beyond context limits - Read, search, and edit files too large to fit in AI context windows
Semantic code navigation - Tree-sitter extracts functions/classes for Python, JS/TS, Rust, Go
Fewer LLM errors - Search/replace editing eliminates line number mistakes common with line-based edits
Smart search - Fuzzy matching, regex, case-insensitive, inverted, and count-only modes
No size limits - Handles multi-GB files via tiered memory strategy (RAM → mmap → streaming)
Related MCP server: Aleph
Quick Start
Prerequisite: Install uv for the uvx command.
{
"mcpServers": {
"largefile": {
"command": "uvx",
"args": ["--from", "largefile", "largefile-mcp"]
}
}
}Tools
Tool | Use For |
| File structure and semantic outline before diving in |
| Finding patterns, counting occurrences, regex matching |
| Reading specific sections; tail/head modes for logs |
| Safe search/replace with automatic backups |
| Recovering from bad edits |
| Browse directory trees with recursive depth control |
| Search patterns across all files in a directory |
When to Use Largefile
Use when:
File exceeds ~1000 lines or 100KB (supports multi-GB files)
Navigating large codebases with semantic structure
Analyzing log files (especially recent entries with tail mode)
Making search/replace edits across large files
Counting occurrences without loading full content
Don't use for:
Small files that fit in context (AI doesn't need help with those)
Binary files (images, executables, compressed)
Usage Examples
Large Codebase Navigation
# Get semantic structure of a large Python file
overview = get_overview("/path/to/large_module.py")
# Returns: 2,847 lines, 15 classes, function outline via Tree-sitter
# Find all class definitions
classes = search_content("/path/to/large_module.py", "class ", fuzzy=False)
# Read complete class with semantic chunking
code = read_content("/path/to/large_module.py", pattern="class UserModel", mode="semantic")Batch Refactoring
# Preview rename across file
preview = edit_content("/path/to/api.py", changes=[
{"search": "process_data", "replace": "transform_data"},
{"search": "old_endpoint", "replace": "new_endpoint"}
], preview=True)
# Apply changes (creates automatic backup)
result = edit_content("/path/to/api.py", changes=[...], preview=False)
# Undo if needed
revert_edit("/path/to/api.py")Log Analysis
# Get log file overview
overview = get_overview("/var/log/app.log")
# Returns: 150,000 lines, 2.1GB
# Read last 500 lines efficiently
recent = read_content("/var/log/app.log", limit=500, mode="tail")
# Count errors without loading content
error_count = search_content("/var/log/app.log", "ERROR", count_only=True, fuzzy=False)
# Find errors with regex
errors = search_content("/var/log/app.log", r"ERROR.*timeout", regex=True)Supported Languages
Tree-sitter semantic analysis for: Python, JavaScript/JSX, TypeScript/TSX, Rust, Go, Java
Other file types use text-based analysis with graceful fallback.
File Size Handling
Size | Strategy |
< 50MB | Full memory loading with AST caching |
50-500MB | Memory-mapped access |
> 500MB | Streaming (tail/head modes recommended) |
Configuration
Environment variables for tuning:
LARGEFILE_MEMORY_THRESHOLD_MB=50 # RAM loading limit
LARGEFILE_MMAP_THRESHOLD_MB=500 # Memory mapping limit
LARGEFILE_FUZZY_THRESHOLD=0.8 # Match sensitivity (0.0-1.0)
LARGEFILE_MAX_SEARCH_RESULTS=20 # Results per search
LARGEFILE_BACKUP_DIR=~/.largefile/backupsDocumentation
API Reference - Detailed tool documentation
Configuration Guide - All environment variables
Examples - More workflow examples
Design Document - Architecture details
Contributing - Development setup
Available Tools
8 toolsedit_contentADestructive
Edit large files using search/replace with fuzzy matching.
Use instead of line-based editing to avoid LLM line number errors. Fuzzy
matching handles whitespace and formatting differences automatically.
Preview mode (default) shows diff without applying. Creates automatic
backup before changes - use revert_edit to undo. Does NOT support regex
in replacement - patterns must be literal text (use fuzzy=true for
flexibility).
Inputs: absolute_file_path (required), changes (required), fuzzy, preview.
get_overviewARead-only
Get file structure, size, and semantic outline for large files (code, logs, data).
Use FIRST when working with any file over 1000 lines or when you need to
understand file structure. Returns: line count, byte size, binary detection,
long line stats, section headings, and suggested search patterns. For code
files, uses Tree-sitter to extract functions, classes, and structure. Does
NOT return file content - use read_content or search_content for that.
Inputs: absolute_file_path (required), changed_lines.
list_directoryARead-only
List the contents of a directory.
Each entry has a type field: 'dir' for directories, 'file' for files.
Use max_depth > 1 to recurse into subdirectories. Automatically ignores
__pycache__, node_modules, and .git. Returns entry type, size in bytes,
and child count for directories.
Inputs: absolute_dir_path (required), max_depth, max_entries, include_hidden.
read_contentARead-only
Read specific portions of large files efficiently.
Use after search_content locates content, or directly with tail/head modes
for logs. Modes: 'lines' (read by offset/limit), 'semantic' (complete
functions/classes via Tree-sitter), 'tail' (last N lines - ideal for logs),
'head' (first N lines). Does NOT search - use search_content first to find
line numbers, then read_content to examine. For files over 500MB, tail/head
modes are most efficient.
Inputs: absolute_file_path (required), offset, limit, pattern, +1 more.
read_enclosingARead-only
Find the enclosing function or class for a specific line number.
Given a file and line number, returns the complete enclosing definition (function, method, class, struct, etc.) containing that line. Use depth=2 to get the parent definition (e.g., the class containing a method). Falls back to a centered context window for unsupported languages or top-level code.
Inputs: absolute_file_path (required), line (required), depth, context_lines.
revert_editADestructive
Restore a file to a previous state from automatic backups.
Use when edit_content made unwanted changes. Backups are created
automatically before each edit. Current state is saved as new backup
before reverting (so revert is reversible). Without backup_id, reverts to
most recent backup. Returns list of available backups with timestamps.
Inputs: absolute_file_path (required), backup_id.
search_contentARead-only
Search large files for text patterns without loading entire content into memory.
Use when finding functions, classes, errors, log entries, or counting
occurrences. Supports: fuzzy matching (handles typos/whitespace), regex
patterns, case-insensitive search, inverted matching (like grep -v), and
count-only mode. Returns ranked matches with line numbers and context
(lines truncated to 500 chars). When count_only=True, returns
{count, pattern, fuzzy_enabled, regex_enabled, case_sensitive, inverted}
instead of the full results structure.
Inputs: absolute_file_path (required), pattern (required), max_results, context_lines, +5 more.
search_directoryARead-only
Search for a text pattern across all files in a directory.
Returns results grouped by file with line numbers and context. Use
include_pattern to filter by file extension (e.g. '*.py'). Automatically
ignores __pycache__, node_modules, and .git. Prefer fuzzy=False (default)
for multi-file search performance.
Inputs: absolute_dir_path (required), pattern (required), include_pattern, max_results, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool has a clearly distinct purpose: editing, overview, reading, searching, listing, reverting, and structural analysis. No two tools overlap in functionality, making it easy for an agent to select the correct one.
All tools follow a consistent verb_noun pattern in snake_case (e.g., edit_content, get_overview, list_directory), with no mixed conventions or vague names.
8 tools is well-scoped for the domain of handling large files. Each tool addresses a specific need (reading, searching, editing, reverting, etc.) without unnecessary extras.
The tool set covers core operations for large files: overview, reading, searching, editing, reverting, and directory listing. Minor gaps like missing file creation or deletion are acceptable given the server's focus on large, existing files.
Maintenance
Related MCP Connectors
Securely search and manage workspace context files for AI agents and teams.
Code-map tools for AI agents: see a repo's structure first, then edit only what matters.
Project memory for every AI. Pick up where you left off in Claude, ChatGPT or Cursor, with a team.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables intelligent handling of large files through smart chunking, search with regex support, line navigation, and streaming capabilities without loading entire files into memory.621 npm18MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to analyze documents larger than their context window by loading files into RAM and querying them via search, navigation, and Python execution tools. Supports recursive reasoning to process massive datasets in chunks using sub-agents.220MIT
- AlicenseNot gradedqualityCmaintenanceLoads entire codebase into LLM context for AI-assisted code understanding and editing.17 npm17MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to inspect and extract data from local CSV, TSV, JSONL and log files far larger than available RAM, using bounded memory, crash-resilient resumable runs, and streamed progress. All file access is confined to user-approved directories, keeping the data private to the machine.MIT