Mcp Grep

What is Mcp Grep about?

Mcp Grep wraps the local grep binary and exposes its functionality through MCP resources and tools, allowing LLM‑driven or programmatic searches without invoking the command line directly.

How to use Mcp Grep?

Installation

• Via Smithery (recommended for Claude Desktop):

  npx -y @smithery/cli install @erniebrodeur/mcp-grep --client claude
  

• Manual installation for any environment:

  pip install mcp-grep
  

Running the server

# start the MCP server
mcp-grep-server

# optional interactive debugging UI
mcp-grep-inspector

Client usage (Python example)

from mcp.client import MCPClient
client = MCPClient()
info = client.get_resource("grep://info")
print(info)
result = client.use_tool("grep", {
    "pattern": "error",
    "paths": ["log.txt"],
    "ignore_case": True,
    "recursive": False
})
print(result)

Key Features

• Retrieves system grep metadata (path, version, supported flags).
• Executes regular‑expression searches with common grep options: case‑insensitive, context lines, max count, fixed‑string, recursive directories.
• Understands natural‑language prompts, simplifying interaction for LLMs.
• Interactive MCP Inspector UI for testing and debugging.
• MIT‑licensed and installable via pip or Smithery.

Use Cases

• Automated code‑base scanning for security patterns (e.g., passwords, API keys).
• Log analysis in AI‑assisted monitoring pipelines.
• Integrating grep searches into conversational agents or chat‑based assistants.
• Rapid prototyping of search‑driven workflows without writing shell scripts.
• Classroom demonstrations of how traditional CLI tools can be wrapped for AI consumption.

FAQ

Q: Do I need Node.js to run Mcp Grep? A: No. The core package is a Python library; Node.js is only required if you install via Smithery, which uses npx for convenience.

Q: Which operating systems are supported? A: Any OS with a standard grep binary (Linux, macOS, BSD, Windows via WSL or GNU grep).

Q: How can I limit the number of results? A: Use the max_count parameter in the tool call or include “show only the first N matches” in the natural‑language prompt.

Q: Can I customize environment variables for the server? A: The server inherits the environment of the process that runs mcp-grep-server. Set variables like PATH or GREPOPTIONS before starting the server if needed.

Q: Is there a way to view grep version information? A: Yes. Call the grep://info resource to receive JSON with the binary path, version string, and supported flags.

MCP-Grep

A grep server implementation that exposes grep functionality through the Model Context Protocol (MCP).

Installation

Installing via Smithery

To install Grep Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @erniebrodeur/mcp-grep --client claude

Manual Installation

pip install mcp-grep

Usage

MCP-Grep runs as a server that can be used by MCP-compatible clients:

# Start the MCP-Grep server
mcp-grep-server

# Or use the MCP Inspector for interactive debugging and testing
mcp-grep-inspector

The server exposes the following MCP functionality:

• Resource: grep://info - Returns information about the system grep binary
• Tool: grep - Searches for patterns in files using the system grep binary

Features

• Information about the system grep binary (path, version, supported features)
• Search for patterns in files using regular expressions
• Support for common grep options:
  • Case-insensitive matching
  • Context lines (before and after matches)
  • Maximum match count
  • Fixed string matching (non-regex)
  • Recursive directory searching
• Natural language prompt understanding for easier use with LLMs
• Interactive debugging and testing through MCP Inspector

Example API Usage

Using the MCP Python client:

from mcp.client import MCPClient

# Connect to the MCP-Grep server
client = MCPClient()

# Get information about the grep binary
grep_info = client.get_resource("grep://info")
print(grep_info)

# Search for a pattern in files
result = client.use_tool("grep", {
    "pattern": "search_pattern",
    "paths": ["file.txt", "directory/"],
    "ignore_case": True,
    "recursive": True
})
print(result)

Natural Language Prompts

MCP-Grep understands natural language prompts, making it easier to use with LLMs. Examples:

# Basic search
Search for 'error' in log.txt

# Case-insensitive search
Find all instances of 'WARNING' regardless of case in system.log

# With context lines
Search for 'exception' in error.log and show 3 lines before and after each match

# Recursive search
Find all occurrences of 'deprecated' in the src directory and its subdirectories

# Fixed string search (non-regex)
Search for the exact string '.*' in config.js

# Limited results
Show me just the first 5 occurrences of 'TODO' in the project files

# Multiple options
Find 'password' case-insensitively in all .php files, show 2 lines of context, and limit to 10 results

MCP Inspector Integration

MCP-Grep includes an MCP Inspector integration for interactive debugging and testing:

# Start the MCP Inspector with MCP-Grep
mcp-grep-inspector

This opens a web-based UI where you can:

• Explore available resources and tools
• Test grep operations with different parameters
• View formatted results
• Debug issues with your grep queries

Development

# Clone the repository
git clone https://github.com/erniebrodeur/mcp-grep.git
cd mcp-grep

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

License

MIT