# Ceregrep MCP Server
[](https://pypi.org/project/ceregrep-mcp/)
[](https://github.com/Swarm-Code/ceregrep-client/blob/master/LICENSE)
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**:
```bash
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)
```bash
# No installation needed! Just use uvx to run it
uvx ceregrep-mcp
```
### Option 2: Install via pip
```bash
pip install ceregrep-mcp
```
### Option 3: Install from source (Development)
```bash
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:
```bash
uvx ceregrep-mcp
```
### Add to Claude Desktop
**Method 1: Using Claude MCP CLI (Easiest)**
```bash
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:
```json
{
"mcpServers": {
"ceregrep": {
"command": "uvx",
"args": ["ceregrep-mcp"]
}
}
}
```
**If you installed via pip:**
```json
{
"mcpServers": {
"ceregrep": {
"command": "ceregrep-mcp"
}
}
}
```
### Add to Other MCP Clients
For any MCP-compatible client, add to your `mcp.json` or equivalent config file:
```json
{
"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`:
```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:
```bash
python --version # Should be ≥ 3.10
uv --version # Should be installed
```
### Query failures
Check ceregrep configuration:
```bash
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
Raw data
{
"_id": null,
"home_page": null,
"name": "ceregrep-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agent, cerebras, ceregrep, llm, mcp, model-context-protocol",
"author": "Swarm-Code",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ea/19/bda0dda8e412e1037c98a1ec72fc295afec3566c9bc8416890fb2d16ae04/ceregrep_mcp-0.2.2.tar.gz",
"platform": null,
"description": "# Ceregrep MCP Server\n\n[](https://pypi.org/project/ceregrep-mcp/)\n[](https://github.com/Swarm-Code/ceregrep-client/blob/master/LICENSE)\n\nMCP (Model Context Protocol) server that exposes ceregrep query capabilities to other agents.\n\n## What is This?\n\nThis 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.\n\n## Features\n\n- **ceregrep_query**: Query ceregrep to find context in codebases\n - Natural language queries (e.g., \"Find all async functions\", \"Explain the auth flow\")\n - Automatic code exploration using ceregrep's bash + grep tools\n - LLM-powered analysis and context gathering\n\n## Prerequisites\n\n1. **Ceregrep CLI installed globally**:\n ```bash\n npm install -g ceregrep\n ```\n\n2. **Python \u2265 3.10** (for pip installation) or **uvx** (for no-install usage)\n\n## Installation\n\n### Option 1: Using uvx (Recommended - No Installation Required)\n\n```bash\n# No installation needed! Just use uvx to run it\nuvx ceregrep-mcp\n```\n\n### Option 2: Install via pip\n\n```bash\npip install ceregrep-mcp\n```\n\n### Option 3: Install from source (Development)\n\n```bash\ncd mcp-server\npip install -e .\n```\n\n## Usage\n\n### Using with uvx (Recommended)\n\nThe easiest way to use ceregrep-mcp is with `uvx`, which runs the package without installation:\n\n```bash\nuvx ceregrep-mcp\n```\n\n### Add to Claude Desktop\n\n**Method 1: Using Claude MCP CLI (Easiest)**\n\n```bash\nclaude mcp add ceregrep uvx ceregrep-mcp\n```\n\nThis automatically adds ceregrep-mcp to your Claude configuration.\n\n**Method 2: Manual Configuration**\n\nEdit your Claude Desktop MCP configuration file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nAdd this configuration:\n\n```json\n{\n \"mcpServers\": {\n \"ceregrep\": {\n \"command\": \"uvx\",\n \"args\": [\"ceregrep-mcp\"]\n }\n }\n}\n```\n\n**If you installed via pip:**\n\n```json\n{\n \"mcpServers\": {\n \"ceregrep\": {\n \"command\": \"ceregrep-mcp\"\n }\n }\n}\n```\n\n### Add to Other MCP Clients\n\nFor any MCP-compatible client, add to your `mcp.json` or equivalent config file:\n\n```json\n{\n \"mcpServers\": {\n \"ceregrep\": {\n \"command\": \"uvx\",\n \"args\": [\"ceregrep-mcp\"],\n \"env\": {}\n }\n }\n}\n```\n\n### Add to Ceregrep Itself (Recursive Pattern)\n\nYou can even use ceregrep's own MCP client to connect to this server! Add to `.ceregrep.json` or `~/.ceregrep.json`:\n\n```json\n{\n \"mcpServers\": {\n \"ceregrep-context\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"ceregrep-mcp\"]\n }\n }\n}\n```\n\nNow ceregrep can delegate context-finding to another instance of itself!\n\n## Available Tools\n\n### ceregrep_query\n\nQuery ceregrep to find context in a codebase.\n\n**Parameters:**\n- `query` (required): Natural language query\n- `cwd` (optional): Working directory to run ceregrep in\n- `model` (optional): LLM model to use\n- `verbose` (optional): Enable verbose output\n\n**Example queries:**\n- \"Find all async functions in this codebase\"\n- \"Explain how the authentication system works\"\n- \"Show me all API endpoints\"\n- \"Find files that handle database connections\"\n- \"Analyze the project architecture\"\n\n## How It Works\n\n1. Agent sends a natural language query to ceregrep_query tool\n2. MCP server invokes the ceregrep CLI with the query\n3. Ceregrep uses its own LLM + bash + grep tools to explore the codebase\n4. Results are returned to the requesting agent\n\nThis creates a **recursive agent** pattern where agents can delegate complex context-finding to specialized sub-agents.\n\n## Configuration\n\nThe MCP server uses the ceregrep CLI, which reads configuration from:\n- `.ceregrep.json` in the working directory\n- `~/.config/ceregrep/config.json` (global config)\n- Environment variables (`ANTHROPIC_API_KEY`, `CEREBRAS_API_KEY`)\n\n## Development\n\n### Project Structure\n\n```\nmcp-server/\n\u251c\u2500\u2500 mcp_server.py # Main MCP server\n\u251c\u2500\u2500 tool_discovery.py # Auto-discovery system\n\u251c\u2500\u2500 tools/\n\u2502 \u251c\u2500\u2500 base_tool.py # Base tool class\n\u2502 \u2514\u2500\u2500 ceregrep_query_tool.py # Ceregrep query tool\n\u251c\u2500\u2500 pyproject.toml # Dependencies\n\u2514\u2500\u2500 README.md # This file\n```\n\n### Adding New Tools\n\n1. Create a new file in `tools/`\n2. Inherit from `BaseTool`\n3. Implement `name`, `description`, `input_schema`, and `execute()`\n4. Restart server - tool is auto-discovered!\n\n## Troubleshooting\n\n### \"ceregrep command not found\"\n\nRun `npm link` in the ceregrep-client directory to install the CLI globally.\n\n### MCP connection errors\n\nEnsure Python \u2265 3.10 and uv are installed:\n```bash\npython --version # Should be \u2265 3.10\nuv --version # Should be installed\n```\n\n### Query failures\n\nCheck ceregrep configuration:\n```bash\nceregrep config # View current config\n```\n\nEnsure API keys are set:\n- `ANTHROPIC_API_KEY` for Claude\n- `CEREBRAS_API_KEY` for Cerebras\n\n## License\n\nAGPL-3.0-or-later\n",
"bugtrack_url": null,
"license": null,
"summary": "MCP server for ceregrep - exposes ceregrep query capabilities to other agents",
"version": "0.2.2",
"project_urls": {
"Documentation": "https://github.com/Swarm-Code/ceregrep-client/blob/master/mcp-server/README.md",
"Homepage": "https://github.com/Swarm-Code/ceregrep-client",
"Issues": "https://github.com/Swarm-Code/ceregrep-client/issues",
"Repository": "https://github.com/Swarm-Code/ceregrep-client"
},
"split_keywords": [
"agent",
" cerebras",
" ceregrep",
" llm",
" mcp",
" model-context-protocol"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9bc0d3c0a7482c8c64cb341181e761e4e20455fc2d2c41bf6b3971e796930a8d",
"md5": "48ff07984a018ec81e73e512e9ee615d",
"sha256": "5cd901d62b1cda23bfbeecbbcffee644d0fe0d33d041de891143dcac19a07385"
},
"downloads": -1,
"filename": "ceregrep_mcp-0.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "48ff07984a018ec81e73e512e9ee615d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7953,
"upload_time": "2025-10-19T23:16:47",
"upload_time_iso_8601": "2025-10-19T23:16:47.546072Z",
"url": "https://files.pythonhosted.org/packages/9b/c0/d3c0a7482c8c64cb341181e761e4e20455fc2d2c41bf6b3971e796930a8d/ceregrep_mcp-0.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ea19bda0dda8e412e1037c98a1ec72fc295afec3566c9bc8416890fb2d16ae04",
"md5": "e608b3d4c08333d3070bb895ec83c140",
"sha256": "318c6b0893aca2facf6e4402f4fd53b19bdf5c2450359a02062697ac4260ccac"
},
"downloads": -1,
"filename": "ceregrep_mcp-0.2.2.tar.gz",
"has_sig": false,
"md5_digest": "e608b3d4c08333d3070bb895ec83c140",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7219,
"upload_time": "2025-10-19T23:16:48",
"upload_time_iso_8601": "2025-10-19T23:16:48.991686Z",
"url": "https://files.pythonhosted.org/packages/ea/19/bda0dda8e412e1037c98a1ec72fc295afec3566c9bc8416890fb2d16ae04/ceregrep_mcp-0.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-19 23:16:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Swarm-Code",
"github_project": "ceregrep-client",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "ceregrep-mcp"
}
JSON
