mcp-grep

What is mcp-grep?

mcp-grep is a Python-based server that exposes the functionality of the grep command-line utility through the Model Context Protocol (MCP). This allows Large Language Models (LLMs) and other MCP-compatible clients to interact with grep for pattern searching and file analysis using natural language prompts.

How to use mcp-grep?

Installation:

• Via Smithery (for Claude Desktop): npx -y @smithery/cli install @erniebrodeur/mcp-grep --client claude
• Manual Installation: pip install mcp-grep

Running the Server:

• Start the MCP-Grep server: mcp-grep-server
• For interactive debugging and testing: mcp-grep-inspector

API Usage (Python Client):

from mcp.client import MCPClient

client = MCPClient()
grep_info = client.get_resource("grep://info")
print(grep_info)

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 queries, making it easy to integrate with LLMs. Examples include:

• "Search for 'error' in log.txt"
• "Find all instances of 'WARNING' regardless of case in system.log"
• "Search for 'exception' in error.log and show 3 lines before and after each match"

Key Features of mcp-grep

• Exposes system grep binary information (path, version, supported features).
• Supports regular expression pattern searching in files.
• Common grep options: case-insensitive matching, context lines, max match count, fixed string matching, recursive directory searching.
• Natural language prompt understanding for LLM integration.
• Interactive debugging and testing via MCP Inspector.

Use Cases of mcp-grep

• LLM Integration: Enable LLMs to perform file content analysis and pattern searching directly.
• Automated Log Analysis: Use LLMs to identify errors, warnings, or specific events in log files.
• Codebase Analysis: Search for specific code patterns, deprecated functions, or security vulnerabilities within large codebases.
• Content Management: Find and extract specific information from text documents.
• Interactive Debugging: Utilize the MCP Inspector for real-time testing and debugging of grep queries.

FAQ about mcp-grep

Q: What is MCP? A: MCP stands for Model Context Protocol, which is a protocol designed to allow language models to interact with external tools and resources.

Q: Can I use mcp-grep with other LLMs besides Claude? A: Yes, mcp-grep is designed to be compatible with any MCP-compatible client, not just Claude Desktop.

Q: Does mcp-grep support all grep functionalities? A: mcp-grep supports common and frequently used grep features, as listed in the "Key Features" section. For a comprehensive list, refer to the project's documentation or the grep man page.

Q: How can I contribute to mcp-grep? A: You can contribute by cloning the repository, installing in development mode (pip install -e ".[dev]"), and running tests (pytest). Refer to the "Development" section in the README for more details.

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