ceregrep-mcp 0.2.2

MCP server for ceregrep - exposes ceregrep query capabilities to other agents

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