How do I use large-repo-mcp-server?

This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

large-repo-mcp-server

by ErenAri

Overview Schema Source Related Servers Discussions Admin

JavaScript

Local

Large Repo MCP Server

Stdio-based Model Context Protocol server designed as a standard toolkit for large and complex repositories. Uses ripgrep for fast, bounded search across codebases of any size.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│  MCP Client (Codex CLI / Claude Desktop / Claude Code)          │
│                                                                 │
│   tools/call ──►  JSON-RPC 2.0 request                          │
│                   Content-Length: N\r\n\r\n{...}                │
└─────────────┬───────────────────────────────────▲───────────────┘
              │ stdin                              │ stdout
              ▼                                    │
┌─────────────────────────────────────────────────────────────────┐
│  large-repo-mcp server                                          │
│                                                                 │
│  ┌──────────┐    ┌────────────┐    ┌──────────────────────┐     │
│  │  Frame   │───►│  JSON-RPC  │───►│    Tool Dispatch     │     │
│  │  Parser  │    │  Router    │    │                      │     │
│  │          │    │            │    │  project_search_rg   │     │
│  │ Content- │    │ initialize │    │  symbol_search       │     │
│  │ Length   │    │ tools/list │    │  read_range          │     │
│  │ framing  │    │ tools/call │    │  list_files          │     │
│  └──────────┘    │ ping       │    └──────────┬───────────┘     │
│                  └────────────┘               │                 │
│                                               │                 │
│  ┌────────────────────────────────────────────▼──────────┐      │
│  │  Security Layer                                       │      │
│  │                                                       │      │
│  │  • Path confinement (resolve + realpath + root check) │      │
│  │  • Command allowlist (rg only, shell: false)          │      │
│  │  • Request size limit (1 MB)                          │      │
│  │  • Response size limit (200 KB)                       │      │
│  │  • Null-byte rejection                                │      │
│  └───────────────────────────┬───────────────────────────┘      │
│                              │                                  │
│                              ▼                                  │
│                     ┌─────────────────┐                         │
│                     │  rg (ripgrep)   │                         │
│                     │  subprocess     │                         │
│                     │                 │                         │
│                     │  • 15s timeout  │                         │
│                     │  • JSON output  │                         │
│                     │  • Streaming    │                         │
│                     └─────────────────┘                         │
│                                                    stderr ──►   │
│                                          structured JSON logs   │
└─────────────────────────────────────────────────────────────────┘

Related MCP server: @atef_andrus/mcp-ripgrep

Request Flow

Client                          Server                         ripgrep
  │                               │                               │
  │  Content-Length: N\r\n\r\n    │                               │
  │  {"jsonrpc":"2.0",            │                               │
  │   "method":"tools/call",...}  │                               │
  │──────────────────────────────►│                               │
  │                               │  validate request size (≤1MB) │
  │                               │  parse JSON-RPC frame         │
  │                               │  validate tool + arguments    │
  │                               │  resolve & confine paths      │
  │                               │                               │
  │                               │  spawn rg --json ...          │
  │                               │──────────────────────────────►│
  │                               │                               │
  │                               │  stream results (line-by-line)│
  │                               │◄──────────────────────────────│
  │                               │                               │
  │                               │  enforce match/byte limits    │
  │                               │  kill rg if limit reached     │
  │                               │                               │
  │  Content-Length: M\r\n\r\n    │                               │
  │  {"jsonrpc":"2.0",            │                               │
  │   "result":{...}}             │                               │
  │◄──────────────────────────────│                               │
  │                               │                               │

Safety Guarantees

Guarantee	Mechanism	Limit
Fast, bounded search	ripgrep with match caps	500 max matches
Response size cap	Byte-level output budget	200 KB
Subprocess timeout	`setTimeout` + `child.kill()`	15 seconds
Path confinement	`path.resolve` + `realpath` + root prefix check	repo root only
Symlink escape prevention	`fs.realpath()` resolves then re-validates	double-checked
Command execution	Allowlist (`rg` only) + `shell: false`	no shell injection
Request size limit	Frame-level rejection before parse	1 MB
Input sanitization	Null-byte rejection, type validation	all tool inputs
Child process cleanup	Tracked set, killed on shutdown signals	`SIGTERM`/`SIGINT`/`exit`

Supported Clients

Codex CLI
Claude Desktop
Claude Code
Any MCP client supporting stdio transport (protocol version 2024-11-05)

Requirements

Node.js 18+
ripgrep (rg) on PATH
- symbol_search requires PCRE2 support (most official packages include it)

Verify ripgrep:

rg --version        # should show version
rg --pcre2-version  # should show PCRE2 version

Install ripgrep:

Platform	Command
macOS	`brew install ripgrep`
Ubuntu/Debian	`sudo apt-get install ripgrep`
Fedora	`sudo dnf install ripgrep`
Windows	`winget install BurntSushi.ripgrep.MSVC`
Cargo	`cargo install ripgrep --features pcre2`

Install

npm install
npm run build

Run

npm start

Default repo root behavior:

If REPO_ROOT is unset, repo root is current working directory (process.cwd()).
Set REPO_ROOT to override explicitly.

PowerShell:

$env:REPO_ROOT = "C:\absolute\path\to\repo"
npm start

MCP Configuration

Codex (Global)

Add to ~/.codex/config.toml:

[mcp_servers.large_repo_mcp]
command = "node"
args = ["C:/absolute/path/to/mcp/dist/server.js"]
startup_timeout_sec = 30

[mcp_servers.large_repo_mcp.env]
REPO_ROOT = "."

Codex (Project-Local)

Add to .codex/config.toml in a project:

[mcp_servers.large_repo_mcp]
command = "node"
args = ["C:/absolute/path/to/mcp/dist/server.js"]
startup_timeout_sec = 30

[mcp_servers.large_repo_mcp.env]
REPO_ROOT = "."

Claude Desktop

Add to Claude Desktop MCP config:

{
  "mcpServers": {
    "large_repo_mcp": {
      "command": "node",
      "args": ["C:/absolute/path/to/mcp/dist/server.js"],
      "env": {
        "REPO_ROOT": "C:/absolute/path/to/target-repo"
      }
    }
  }
}

Claude Code

Add to .mcp.json in a project or ~/.claude/mcp.json globally:

{
  "mcpServers": {
    "large_repo_mcp": {
      "command": "node",
      "args": ["C:/absolute/path/to/mcp/dist/server.js"],
      "env": {
        "REPO_ROOT": "."
      }
    }
  }
}

Environment Variables

Variable	Default	Description
`REPO_ROOT`	`process.cwd()`	Repository root directory
`LARGE_REPO_MCP_LOG_LEVEL`	`error`	Log level: `error`, `warn`, `info`, `debug`
`LARGE_REPO_MCP_DEBUG`	—	Set to `1` to force debug logging

Tools

`project_search_rg`

Search the repository with ripgrep. Supports regex patterns and optional glob filters.

┌──────────────────────────────────────────────────────┐
│  project_search_rg                                   │
│                                                      │
│  Input                          Output               │
│  ─────                          ──────               │
│  pattern (string, required)     matches[]            │
│  globs (string[], max 50)         .path              │
│  maxMatches (1-500, def 100)      .line              │
│                                   .column            │
│                                   .text              │
│                                   .submatches[]      │
│                                 truncated            │
│                                 truncateReason       │
│                                 timedOut             │
│                                 serverVersion        │
│                                 durationMs           │
└──────────────────────────────────────────────────────┘

Example call:

{
  "name": "project_search_rg",
  "arguments": {
    "pattern": "TODO|FIXME",
    "globs": ["*.ts", "*.tsx"],
    "maxMatches": 50
  }
}

`symbol_search`

Search for an exact symbol using word-boundary matching (\b...\b). Auto-detects project type (TypeScript or Python) and scopes file types accordingly.

┌──────────────────────────────────────────────────────┐
│  symbol_search                                       │
│                                                      │
│  Input                          Output               │
│  ─────                          ──────               │
│  symbol (string, required)      projectType          │
│  maxMatches (1-500, def 100)    matchMode            │
│                                 matches[]            │
│                                   .path              │
│  Detection logic:                 .line              │
│  ┌────────────────────┐          .column             │
│  │ tsconfig.json?     │          .text               │
│  │   yes → typescript │          .submatches[]       │
│  │   no → check files │                              │
│  │   .py only → python│                              │
│  │   .ts only → ts    │                              │
│  │   fallback → ts    │                              │
│  └────────────────────┘                              │
└──────────────────────────────────────────────────────┘

Example call:

{
  "name": "symbol_search",
  "arguments": {
    "symbol": "handleRequest",
    "maxMatches": 20
  }
}

`read_range`

Read a specific line range from a file. Path must be relative and resolve inside the repo root.

┌──────────────────────────────────────────────────────┐
│  read_range                                          │
│                                                      │
│  Input                          Output               │
│  ─────                          ──────               │
│  path (relative, required)      path (normalized)    │
│  startLine (int, required)      requestedLines       │
│  endLine (int, required)        returnedLines        │
│                                 lines[]              │
│  Constraints:                     .line              │
│  • max 500 lines per call         .text              │
│  • path confined to repo root   truncated            │
│  • symlinks resolved + checked  truncateReason       │
└──────────────────────────────────────────────────────┘

Example call:

{
  "name": "read_range",
  "arguments": {
    "path": "src/server.ts",
    "startLine": 1,
    "endLine": 50
  }
}

`list_files`

List repository files using ripgrep --files with optional glob filters. Excludes .git, node_modules, dist, build, and coverage by default.

┌──────────────────────────────────────────────────────┐
│  list_files                                          │
│                                                      │
│  Input                          Output               │
│  ─────                          ──────               │
│  globs (string[], max 50)       files[] (paths)      │
│  maxResults (1-500, def 500)    returned             │
│                                 truncated            │
│  Auto-excluded dirs:            truncateReason       │
│  .git, node_modules, dist,      timedOut             │
│  build, coverage                                     │
└──────────────────────────────────────────────────────┘

Example call:

{
  "name": "list_files",
  "arguments": {
    "globs": ["src/**/*.ts"],
    "maxResults": 100
  }
}

Project Type Detection

The server auto-detects whether a repository is TypeScript or Python to scope symbol_search file types. Detection runs once per process and is cached.

                    ┌─────────────────────┐
                    │  tsconfig.json      │
                    │  exists?            │
                    └──────┬──────────────┘
                     yes   │         no
                ┌──────────┘         │
                ▼                    ▼
         ┌──────────┐    ┌────────────────────┐
         │TYPESCRIPT│    │ Python project     │
         └──────────┘    │ file exists?       │
                         │ (pyproject.toml,   │
                         │  requirements.txt, │
                         │  setup.py, etc.)   │
                         └──────┬─────────────┘
                          yes   │         no
                     ┌──────────┤          │
                     ▼          │          ▼
              ┌────────────┐   │  ┌──────────────────┐
              │package.json│   │  │ package.json     │
              │  exists?   │   │  │ exists?          │
              └─────┬──────┘   │  └──────┬───────────┘
               yes  │     no   │    yes  │       no
                │   │      │   │     │   │        │
                ▼   │      ▼   │     ▼   │        ▼
          ┌────────┐│ ┌──────┐ │ ┌──────────┐ ┌──────────────┐
          │  Both  ││ │PYTHON│ │ │TYPESCRIPT│ │ Count .ts vs │
          │  scan  ││ └──────┘ │ └──────────┘ │ .py files    │
          │ files  │▼          ▼              └──────┬───────┘
          └───┬────┘     ┌──────────┐          more  │  more
              │          │ No pkg,  │          .py   │  .ts
              ▼          │ has py   │           │    │
       ┌────────────┐    │ file →   │           ▼    ▼
       │ .py only → │    │ PYTHON   │      ┌──────┐ ┌──┐
       │   PYTHON   │    └──────────┘      │PYTHON│ │TS│
       │ .ts only → │                      └──────┘ └──┘
       │   TS       │
       │ fallback → │
       │   TS       │
       └────────────┘

Dev Workflow

npm run typecheck    # type-check without emitting
npm test             # build + run unit & integration tests
npm run lint         # run ESLint
npm run format:check # check Prettier formatting

Troubleshooting

Problem	Solution
`rg` not found	Install ripgrep and ensure it is on `PATH`
`symbol_search` PCRE2 error	Install ripgrep with PCRE2 support (most official packages include it)
`Request exceeds 1048576 bytes`	Split large requests; max inbound JSON-RPC frame body is 1 MB
`truncated: true`	Increase `maxMatches`/`maxResults` (up to bounds), narrow your query, or add globs
No results from `symbol_search`	Check `projectType` in response — detection may have picked the wrong language; use `project_search_rg` as a fallback

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

This server cannot be deployed

Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

Maintenance

ActivityNo data

ResponsivenessOutdated data

Resources

Related MCP Connectors

prover
com.axiomatic-ai
Lean 4 MCP server: compile, prove theorems, and formalize math with Mathlib.
Developer Tools Code Analysis Research & Data
2
https://prover.axiomatic-ai.com/mcp/
SubstrateB
co.trysubstrate
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Developer Tools Knowledge & Memory
131
https://app.trysubstrate.co/mcp
siGit
si.sigit
MCP server for siGit (sigit.si): browse repos, search code, manage PRs/issues, web search.
Version Control Developer Tools
26
https://sigit.si/api/v1/mcp
Meeba BrainA
io.github.meemoprasad
Repository knowledge graph MCP server for codebase understanding and debugging.
Code Analysis Developer Tools
51
https://meeba-context-mcp-469248886325.us-central1.run.app/mcp

Related MCP Servers

@codesift/mcp
Developer Tools Code Analysis Search
rutvikchandla3
A
license
Not graded
quality
D
maintenance
MCP server for local-first lexical code search, providing tools for searching code, finding symbols, and reading chunks from indexed repositories.
Updated 5 months ago (2026-06-26 13:19 UTC)
MIT
@atef_andrus/mcp-ripgrep
Developer Tools File Systems Command Line
AtefAndrus
A
license
A
quality
C
maintenance
An MCP server that wraps ripgrep to provide powerful text search, search-and-replace, file listing, and file type listing capabilities within a defined scope.
Updated 2 months ago (2026-09-01 12:10 UTC)
6
29 npm
MIT
space-ngrams
Code Analysis Developer Tools
dev993848
A
license
Not graded
quality
Not graded
maintenance
MCP server that enables AI agents to search code, find files, and read files in a codebase at lightning speed using ripgrep.
Updated 8 months ago (2026-03-29 16:10 UTC)
MIT
leantoken
Code Analysis Developer Tools
morluto
A
license
Not graded
quality
B
maintenance
Local-first code intelligence MCP server that enables coding agents to search code, inspect structure, read exact ranges, and explore Git history with explicit token budgets.
Updated 5 days ago (2026-11-09 09:14 UTC)
158
Apache 2.0

Large Repo MCP Server

Architecture

Request Flow

Safety Guarantees

Supported Clients

Requirements

Install

Run

MCP Configuration

Codex (Global)

Codex (Project-Local)

Claude Desktop

Claude Code

Environment Variables

Tools

project_search_rg

symbol_search

read_range

list_files

Project Type Detection

Dev Workflow

Troubleshooting

License

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

@codesift/mcp

@atef_andrus/mcp-ripgrep

space-ngrams

leantoken

`project_search_rg`

`symbol_search`

`read_range`

`list_files`