Overview

This MCP (Model Context Protocol) server is a lightweight Python service that brings grep-style file search to LLMs and other MCP-aware agents. It exposes a searchable tool over the MCP so a model can ask for occurrences of a regular expression or plain-text pattern inside a filesystem, receive matched lines and contextual lines, and filter searches by recursion and case sensitivity.

The server is useful when you need programmatic, model-driven access to repository contents, log files, or local datasets. Instead of returning full files or relying on embeddings, the MCP grep tool returns focused excerpts with filename and line numbers, letting downstream LLM reasoning remain grounded in precise source text.

Features

Recursive search through directories
Case-insensitive or case-sensitive matching
Support for regular expressions or literal patterns
Configurable context lines (before/after)
Limits on number of results per request
Returns structured matches: filename, line number, matched line, surrounding context
Built to run as an MCP tool so LLMs can call it during conversations or chains

Installation / Configuration

Clone and run locally, or install directly from the repository.

Clone & run (recommended for development)

git clone https://github.com/erniebrodeur/mcp-grep.git
cd mcp-grep
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
# run the server (example using uvicorn/FastAPI)
uvicorn mcp_grep.server:app --host 127.0.0.1 --port 3333

Install with pip (if packaged)

pip install git+https://github.com/erniebrodeur/mcp-grep.git
# then run a provided entrypoint if available:
mcp-grep --host 127.0.0.1 --port 3333

Environment variables and CLI flags (typical)

MCP_HOST: host address (default 127.0.0.1)
MCP_PORT: port (default 3333)
ROOT_DIR: base directory to search (default current working directory)
MAX_RESULTS: default maximum matches returned per request

Adjust the command line or environment to point the server at the directory you want to make searchable.

Available Tools / Resources

The server exposes a primary MCP tool, commonly named grep or search_files. The tool accepts JSON arguments and returns structured JSON results.

Common request parameters:

path (string): file or directory to search (relative to server root)
pattern (string): regex or literal to match
recursive (bool): whether to descend into subdirectories
case_sensitive (bool): whether the match is case-sensitive
regex (bool): interpret pattern as a regular expression
context (int): number of context lines before/after each match
max_results (int): max number of matches to return

Example API request shape

{
  "tool": "grep",
  "args": {
    "path": "src/",
    "pattern": "TODO",
    "recursive": true,
    "case_sensitive": false,
    "regex": false,
    "context": 2,
    "max_results": 20
  }
}

Example response shape

{
  "matches": [
    {
      "file": "src/main.py",
      "line": 42,
      "text": "    # TODO: improve error handling",
      "context_before": ["def do_work():", "    try:"],
      "context_after": ["    except Exception as e:", "        log(e)"]
    }
  ],
  "count": 1,
  "truncated": false
}

If the server follows the MCP standard, it will also provide tool metadata (name, description, input schema) via a discovery endpoint so LLM tool-choosers can inspect capabilities.

Use Cases

Codebase exploration: Ask an LLM to find all occurrences of a function name or TODO comments across a repository. The model can then decide next steps (edit, refactor, summarize) using concrete snippets.
Log analysis: Search large logs for error codes or stack traces. Return context lines so the model can infer causal sequences without loading whole files.
Compliance and auditing: Locate sensitive keywords (e.g., “password”, “secret”) across project files and produce line-level evidence for review.
Data discovery for prompts: Retrieve a handful of relevant lines from dataset files that can be included as context to a generation task without embedding the entire file.

Concrete example (curl)

curl -sS -X POST http://127.0.0.1:3333/call \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "grep",
    "args": {
      "path": "logs/",
      "pattern": "ERROR 5\\d{2}",
      "recursive": true,
      "regex": true,
      "case_sensitive": false,
      "context": 1,
      "max_results": 10
    }
  }'

Tips and Best Practices

Set a reasonable max_results to avoid returning huge payloads to the model.
Restrict the server root to a safe directory (do not expose the whole filesystem).
Use regex with care — validate or sandbox patterns if user-provided.
Combine grep output with an LLM summarization step that consumes the structured matches rather than raw files.

Repository and issues

Source code, examples, and issues: https://github.com/erniebrodeur/mcp-grep

This MCP grep server is intended to be a practical building block for model-driven developer workflows where precise, line-level evidence from files improves the reliability of LLM actions.

Python MCP Server: Grep with Recursive Search