Ceregrep MCP Server

MCP (Model Context Protocol) server that exposes ceregrep query capabilities to other agents.

What is This?

This MCP server allows any MCP-compatible agent (like Claude Desktop) to use ceregrep as a tool for querying and analyzing codebases. Instead of the agent manually using bash and grep, it can ask ceregrep (which has its own LLM-powered analysis) to find context.

Features

• ceregrep_query: Query ceregrep to find context in codebases
  • Natural language queries (e.g., "Find all async functions", "Explain the auth flow")
  • Automatic code exploration using ceregrep's bash + grep tools
  • LLM-powered analysis and context gathering

Prerequisites

1. Ceregrep CLI installed globally:

   npm install -g ceregrep
   

2. Python ≥ 3.10 (for pip installation) or uvx (for no-install usage)

Installation

Option 1: Using uvx (Recommended - No Installation Required)

# No installation needed! Just use uvx to run it
uvx ceregrep-mcp

Option 2: Install via pip

pip install ceregrep-mcp

Option 3: Install from source (Development)

cd mcp-server
pip install -e .

Usage

Using with uvx (Recommended)

The easiest way to use ceregrep-mcp is with uvx, which runs the package without installation:

uvx ceregrep-mcp

Add to Claude Desktop

Method 1: Using Claude MCP CLI (Easiest)

claude mcp add ceregrep uvx ceregrep-mcp

This automatically adds ceregrep-mcp to your Claude configuration.

Method 2: Manual Configuration

Edit your Claude Desktop MCP configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "ceregrep": {
      "command": "uvx",
      "args": ["ceregrep-mcp"]
    }
  }
}

If you installed via pip:

{
  "mcpServers": {
    "ceregrep": {
      "command": "ceregrep-mcp"
    }
  }
}

Add to Other MCP Clients

For any MCP-compatible client, add to your mcp.json or equivalent config file:

{
  "mcpServers": {
    "ceregrep": {
      "command": "uvx",
      "args": ["ceregrep-mcp"],
      "env": {}
    }
  }
}

Add to Ceregrep Itself (Recursive Pattern)

You can even use ceregrep's own MCP client to connect to this server! Add to .ceregrep.json or ~/.ceregrep.json:

{
  "mcpServers": {
    "ceregrep-context": {
      "type": "stdio",
      "command": "uvx",
      "args": ["ceregrep-mcp"]
    }
  }
}

Now ceregrep can delegate context-finding to another instance of itself!

Available Tools

ceregrep_query

Query ceregrep to find context in a codebase.

Parameters:

• query (required): Natural language query
• cwd (optional): Working directory to run ceregrep in
• model (optional): LLM model to use
• verbose (optional): Enable verbose output

Example queries:

• "Find all async functions in this codebase"
• "Explain how the authentication system works"
• "Show me all API endpoints"
• "Find files that handle database connections"
• "Analyze the project architecture"

How It Works

1. Agent sends a natural language query to ceregrep_query tool
2. MCP server invokes the ceregrep CLI with the query
3. Ceregrep uses its own LLM + bash + grep tools to explore the codebase
4. Results are returned to the requesting agent

This creates a recursive agent pattern where agents can delegate complex context-finding to specialized sub-agents.

Configuration

The MCP server uses the ceregrep CLI, which reads configuration from:

• .ceregrep.json in the working directory
• ~/.config/ceregrep/config.json (global config)
• Environment variables (ANTHROPIC_API_KEY, CEREBRAS_API_KEY)

Development

Project Structure

mcp-server/
├── mcp_server.py           # Main MCP server
├── tool_discovery.py       # Auto-discovery system
├── tools/
│   ├── base_tool.py        # Base tool class
│   └── ceregrep_query_tool.py  # Ceregrep query tool
├── pyproject.toml          # Dependencies
└── README.md               # This file

Adding New Tools

1. Create a new file in tools/
2. Inherit from BaseTool
3. Implement name, description, input_schema, and execute()
4. Restart server - tool is auto-discovered!

Troubleshooting

"ceregrep command not found"

Run npm link in the ceregrep-client directory to install the CLI globally.

MCP connection errors

Ensure Python ≥ 3.10 and uv are installed:

python --version  # Should be ≥ 3.10
uv --version      # Should be installed

Query failures

Check ceregrep configuration:

ceregrep config  # View current config

Ensure API keys are set:

• ANTHROPIC_API_KEY for Claude
• CEREBRAS_API_KEY for Cerebras

License

AGPL-3.0-or-later