Optimizing Claude Code Search with Semble MCP — 98% Token Reduction Explained
What is Semble MCP?
Semble MCP is a fast local code search server built specifically for AI coding agents. It's designed to give agents like Claude Code, Cursor, and OpenAI Codex a smarter way to explore code — more intelligent than grep, lighter than RAG.
Typical AI agents search code using a mix of grep, ripgrep, full file reads, and embeddings. Semble replaces all of that with a purpose-built approach.
"Where's the auth logic?"
"Implementation of save model"
"Firebase initialization"
These kinds of natural language queries return only the relevant code snippets, fast.
Key Features
Ultra-Fast Local Processing
Semble runs on CPU only — no GPU required.
- Repository index generation: ~250ms
- Search: ~1.5ms
Dramatic Token Reduction
Compared to "grep + file read" workflows, Semble uses roughly 98% fewer tokens to surface the code you need. For long sessions or large projects with Claude Code, this translates to significant cost savings.
Security: Fully Local by Design
The official documentation highlights:
- No API key required
- No external network communication
- Operates entirely on local paths
Index generation, search, embedding creation, and BM25 search all happen on your local machine.
Setting Up with Claude Code
You'll need uv. Add Semble with this command:
claude mcp add semble -s user -- uvx --from "semble[mcp]" semble
The package is fetched from PyPI on install, but all subsequent operations run locally.
Combining with Sub-agents
In addition to the MCP version, Semble also has a CLI version. Since Claude Code sub-agents can't always use MCP, it's recommended to explicitly reference the CLI version in your CLAUDE.md or AGENTS.md:
Use `semble search` instead of grep for codebase exploration.
This ensures all agents consistently use Semble across your workflow.
How to Use It
# Natural language search
semble search "authentication flow" ./my-project
semble search "Firebase initialization" ./my-project
semble search "form submission handler" ./my-project --top-k 10
# Find related code (specify file path and line number)
semble find-related src/auth.py 42 ./my-project
Role Separation with Other Tools
Semble is a code search specialist. It's important to understand how it fits alongside other MCP tools:
| Tool | Role |
|---|---|
| Semble | Search your own codebase |
| context7 | Fetch official library documentation |
| filesystem MCP | Read and write files |
| git MCP | Interact with Git |
In practice:
- context7 → "What's the official Jetpack Compose API?"
- Semble → "Find Compose code in my project"
Build, lint, test execution, and database operations are outside Semble's scope.
Who Benefits Most
High-Impact Use Cases
- Large repositories
- Android projects (Jetpack Compose, Firebase, multi-module setups)
- Workflows using AGENTS.md with many sub-agents
- Long-term, continuous Claude Code usage
Lower-Priority Use Cases
- Small repositories (just a few files)
- One-off tasks
Security Considerations
While Semble itself is fully local, there are a few things to keep in mind.
Search Results Are Passed to the LLM
Semble doesn't send your code externally — but the search results it returns are passed to Claude Code, and from there to the LLM.
Local code
↓ Semble search (local only)
↓ Results passed to Claude
↓ LLM processes
So the concern isn't Semble itself — it's the LLM receiving your code.
Example of a Secure Setup
If security is a priority, keep external-communication MCPs to a minimum:
Claude Code
├ Semble (local)
├ filesystem MCP (local)
├ git MCP (local)
└ terminal (local)
If you're working with sensitive or proprietary code, checking the LLM's telemetry and conversation retention policies matters more than Semble's own design.
Summary
Semble MCP is a high-value tool for engineers running Claude Code seriously.
- Up to 98% token cost reduction
- Natural language code search
- Fully local and secure
- Even more powerful when combined with sub-agents
Replacing grep-heavy file scanning with Semble meaningfully improves agent efficiency. If you're working on large projects or multi-agent setups, it's worth adding early.