GrepAI MCP Integration with Claude Code
This skill covers integrating GrepAI with Claude Code using the Model Context Protocol (MCP).
When to Use This Skill
- Setting up GrepAI in Claude Code
- Enabling semantic search for AI coding assistant
- Configuring MCP server for Claude
- Troubleshooting Claude Code integration
What is MCP?
Model Context Protocol (MCP) allows AI assistants to use external tools. GrepAI provides an MCP server that gives Claude Code:
- Semantic code search
- Call graph analysis
- Index status monitoring
Prerequisites
- GrepAI installed
- Ollama running (or other embedding provider)
- Project indexed (
grepai watch)
- Claude Code installed
Quick Setup
One command to add GrepAI to Claude Code:
claude mcp add grepai -- grepai mcp-serve
That's it! Claude Code can now use GrepAI tools.
Manual Configuration
If you prefer manual setup, add to Claude Code's MCP config:
Location
- macOS/Linux:
~/.claude/mcp.json
- Windows:
%APPDATA%\Claude\mcp.json
Configuration
{
"mcpServers": {
"grepai": {
"command": "grepai",
"args": ["mcp-serve"]
}
}
}
With Working Directory
If you want GrepAI to always use a specific project:
{
"mcpServers": {
"grepai": {
"command": "grepai",
"args": ["mcp-serve"],
"cwd": "/path/to/your/project"
}
}
}
Verifying Installation
Check MCP Server
grepai mcp-serve
You should see:
GrepAI MCP Server started
Listening for requests...
In Claude Code
Ask Claude:
"Search the codebase for authentication code"
Claude should use the grepai_search tool.
Available Tools
Once connected, Claude Code has access to these tools:
| Tool |
Description |
Parameters |
grepai_search |
Semantic code search |
query (required), limit, compact |
grepai_trace_callers |
Find function callers |
symbol (required), compact |
grepai_trace_callees |
Find function callees |
symbol (required), compact |
grepai_trace_graph |
Build call graph |
symbol (required), depth |
grepai_index_status |
Check index health |
verbose (optional) |
Tool Usage Examples
Semantic Search
Claude request:
"Find code related to user authentication"
Claude uses:
{
"tool": "grepai_search",
"parameters": {
"query": "user authentication",
"limit": 5,
"compact": true
}
}
Trace Analysis
Claude request:
"What functions call the Login function?"
Claude uses:
{
"tool": "grepai_trace_callers",
"parameters": {
"symbol": "Login",
"compact": true
}
}
Index Status
Claude request:
"Is the code index up to date?"
Claude uses:
{
"tool": "grepai_index_status",
"parameters": {
"verbose": true
}
}
Compact Mode
By default, MCP tools return compact JSON to minimize tokens:
{
"q": "authentication",
"r": [
{"s": 0.92, "f": "src/auth/middleware.go", "l": "15-45"},
{"s": 0.85, "f": "src/auth/jwt.go", "l": "23-55"}
],
"t": 2
}
This reduces token usage by ~80% compared to full content.
Working Directory
The MCP server uses the current working directory. Ensure:
- GrepAI is initialized in your project
- Index exists (run
grepai watch first)
- Start Claude Code from your project directory
Option 1: Start Claude from Project Directory
cd /path/to/your/project
claude
Option 2: Configure CWD in MCP Config
{
"mcpServers": {
"grepai": {
"command": "grepai",
"args": ["mcp-serve"],
"cwd": "/path/to/your/project"
}
}
}
Multiple Projects
For multiple projects, you can:
Option 1: Multiple MCP Servers
{
"mcpServers": {
"grepai-frontend": {
"command": "grepai",
"args": ["mcp-serve"],
"cwd": "/path/to/frontend"
},
"grepai-backend": {
"command": "grepai",
"args": ["mcp-serve"],
"cwd": "/path/to/backend"
}
}
}
Option 2: Use Workspaces
grepai workspace create my-workspace
grepai workspace add my-workspace /path/to/frontend
grepai workspace add my-workspace /path/to/backend
{
"mcpServers": {
"grepai": {
"command": "grepai",
"args": ["mcp-serve", "--workspace", "my-workspace"]
}
}
}
Troubleshooting
Tool Not Available
❌ Problem: Claude doesn't see GrepAI tools
✅ Solutions:
- Restart Claude Code after config changes
- Check MCP config syntax (valid JSON)
- Verify
grepai is in PATH
- Test:
grepai mcp-serve manually
Search Returns No Results
❌ Problem: Searches return empty
✅ Solutions:
- Ensure
grepai watch has run
- Check working directory has
.grepai/
- Verify index exists:
grepai status
Connection Refused
❌ Problem: MCP server won't start
✅ Solutions:
- Check Ollama is running:
curl http://localhost:11434/api/tags
- Verify config:
cat .grepai/config.yaml
- Run
grepai mcp-serve manually to see errors
Wrong Project Indexed
❌ Problem: Results from wrong codebase
✅ Solutions:
- Check
cwd in MCP config
- Start Claude from correct directory
- Verify with
grepai_index_status tool
Best Practices
- Keep index updated: Run
grepai watch --background
- Use compact mode: Reduces token usage
- Set working directory: Explicit
cwd in config
- Check status first: Use
grepai_index_status
- Restart after config: Claude needs restart for MCP changes
Removing Integration
To remove GrepAI from Claude Code:
claude mcp remove grepai
Or manually edit ~/.claude/mcp.json and remove the grepai entry.
Output Format
Successful MCP setup:
✅ GrepAI MCP Integration Configured
Claude Code: ~/.claude/mcp.json
Server: grepai mcp-serve
Status: Connected
Available tools:
- grepai_search (semantic code search)
- grepai_trace_callers (find callers)
- grepai_trace_callees (find callees)
- grepai_trace_graph (call graphs)
- grepai_index_status (index health)
Claude can now search your code semantically!
