MCP Ripgrep Pro

Fast Windows-only MCP server for code search and editing. It uses rg.exe directly with shell: false, returns compact JSON for low-token code navigation, caches reads, supports batch operations, and creates lightweight backups before mutations.

Windows only. This project is intentionally optimized for Windows 10/11 and rg.exe.

Credit

This project is based on the original mcollina/mcp-ripgrep MCP server by Matteo Collina. This fork/rewrite keeps the MIT license and adds a Windows-only search/edit workflow, compact low-token tool calls, batch operations, backups, and direct code editing tools.

Requirements

Windows 10/11
Node.js 20+
ripgrep available as rg.exe or rg
Git for the patch tool

Install

Clone and build on Windows:

git clone https://github.com/AlwaysAnticheat/mcp-test.git
cd mcp-test
npm.cmd install
npm.cmd test
npm.cmd run build
npm.cmd link

Verify the command is available:

where.exe mcp-ripgrep
where.exe mcp-ripgrep.cmd

For local development in this checkout:

npm.cmd install
npm.cmd test

PowerShell may block npm.ps1 on some Windows systems. Use npm.cmd if that happens.

MCP Config

For Cursor, put this in your project at .cursor/mcp.json. Cursor resolves ${workspaceFolder} to the open project, so relative tool paths like src/Main.cpp work naturally:

{
  "mcpServers": {
    "ripgrep-pro": {
      "command": "mcp-ripgrep.cmd",
      "args": [],
      "env": {
        "MCP_RG_ROOTS": "${workspaceFolder}",
        "MCP_RG_WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

For a global Cursor config that should work across any project, use the same ${workspaceFolder} form if your client supports variable expansion.

By default, the server accepts any absolute path. Relative paths are resolved from MCP_RG_WORKSPACE_ROOT.

{
  "mcpServers": {
    "ripgrep-pro": {
      "command": "mcp-ripgrep.cmd",
      "args": [],
      "env": {
        "MCP_RG_WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Tools

x: compact universal tool for low-token agent calls.
search: ripgrep JSON search with regex, literal, smart-case, glob, type, hidden, PCRE2, context, timeout, and byte limits.
search_many: run many searches in one MCP call.
files: ignore-aware file listing through ripgrep.
count: count matching lines or total matches.
read: bounded line-range file reads.
read_many: read many bounded ranges in one MCP call.
replace: exact text replacement with occurrence checks and dry-run support.
replace_many: validated multi-edit exact replacements.
replace_range: replace a 1-based inclusive line range.
insert: insert text before or after a 1-based line.
delete_range: delete a 1-based inclusive line range.
write: create or overwrite workspace files.
rename: rename or move a file or directory.
patch: apply unified diffs through git apply.
symbols: fast symbol-like search for functions, classes, structs, enums, interfaces, and methods.
batch: run many tool calls in one MCP request.
doctor: diagnose Windows path, tool, cache, and write access state.
info: show roots, platform, limits, and ripgrep version.

Compact Usage

Use x for the lowest-token calls:

{"op":"r","f":"src/Main.cpp","s":1,"e":80}

{"op":"s","p":"WinMain","f":"src","n":20}

{"op":"rep","f":"src/Main.cpp","old":"oldText","new":"newText"}

{"op":"b","items":[{"op":"r","f":"src/Main.cpp","s":1,"e":40},{"op":"s","p":"JNI_OnLoad","f":"src","n":10}]}

Compact ops:

s: search
sm: search_many
f: files
c: count
r: read
rm: read_many
rep: replace
repm: replace_many
rr: replace_range
i: insert
d: delete_range
w: write
mv: rename
p: patch
sym: symbols
b: batch
doc: doctor

Common compact args:

f: file or path
p: pattern or patch text
q: symbol query
s: start line
e: end line
t: text/content
n: limit
old: old exact text
new: new exact text
items: batch/list payload
dry: dry run

Responses use compact keys to reduce token usage, for example:

f: file
t: text
s / e: start/end line
n: total lines or limit-dependent count
c: count
m: matches
r: results
rep: replacements
bak: backup
h: sha256

Environment

MCP_RG_ROOTS: allowed workspace roots separated by the OS path delimiter.
MCP_RG_WORKSPACE_ROOT: base directory used for relative paths like src/Main.cpp.
MCP_RG_RESTRICT_ROOTS: set to 1 to restrict access to MCP_RG_ROOTS.
MCP_RG_BACKUPS: set to 0 to disable .mcp-ripgrep-backups.
RG_PATH: explicit path to rg.exe.
MCP_RG_TIMEOUT_MS: default process timeout.
MCP_RG_MAX_BYTES: default process output cap.

All file operations allow any path by default. If MCP_RG_RESTRICT_ROOTS=1 is set, file operations are restricted to MCP_RG_ROOTS.

Backups are created before mutating existing files unless MCP_RG_BACKUPS=0 is set.

MCP Servers