Skip to main content
Glama

Largefile MCP Server

Navigate, search, and edit large codebases, logs, and data files that exceed AI context limits.

CI PyPI version Python 3.10+ License: MIT

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

get_overview

File structure and semantic outline before diving in

search_content

Finding patterns, counting occurrences, regex matching

read_content

Reading specific sections; tail/head modes for logs

edit_content

Safe search/replace with automatic backups

revert_edit

Recovering from bad edits

list_directory

Browse directory trees with recursive depth control

search_directory

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/backups

Documentation

Available Tools

8 tools
edit_contentA
Destructive

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_overviewA
Read-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_directoryA
Read-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_contentA
Read-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_enclosingA
Read-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_editA
Destructive

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_contentA
Read-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_directoryA
Read-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

    A4.4/5.0

    Scored across 8 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      220
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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