AmanMCP: Zero-Config Local RAG Tool Integrating with Claude AI via MCP for Hybrid Search

Amanmcp

AmanMCP is a privacy-first, zero-configuration local code library retrieval-augmented generation (RAG) tool that integrates with Claude AI through the MCP protocol, providing hybrid search functionality. It runs entirely locally without the need for an internet connection.

Developer tools Search tools #Local RAG #Code search #Privacy-first #Hybrid retrieval .Go

rating : 2.5 points

downloads : 4.8K

update time : 2026-03-12

Open Site

What is AmanMCP?

AmanMCP is a local code search assistant designed specifically for developers. It's like the intelligent brain of your code library, capable of understanding your code structure and semantics. When you ask a question to Claude AI, AmanMCP will find the most relevant code snippets from your code library as context, helping Claude provide more accurate answers. The entire process runs entirely on your computer, and your code will never leave your device.

How to use AmanMCP?

Using AmanMCP is very simple: 1) Install Ollama and AmanMCP; 2) Run the initialization command in your project directory; 3) Restart Claude Code; 4) Start asking questions in natural language. AmanMCP will automatically index your code and communicate with Claude in the background without your manual management.

Use cases

AmanMCP is particularly suitable for the following scenarios: • Explore unfamiliar code libraries: Quickly find relevant functions and classes. • Code review: Find the implementation of specific functions. • Code refactoring: Understand code dependencies. • Learn project structure: Understand the architecture of large projects. • Daily development: Quickly locate the code that needs to be modified.

Main features

Hybrid search technology

Combines keyword search (BM25) and semantic search (vector), which can not only precisely match keywords but also understand the query intent. For example, when searching for 'login function', it can find both the code containing 'login' and the code that handles authentication but does not contain this keyword.

Intelligent code chunking

Analyzes the code structure based on the abstract syntax tree (AST) to ensure that logical units such as functions and classes remain intact and are not cut off in the middle, improving the accuracy of search results.

Privacy-first design

All processing is done locally without the need for an internet connection. No user data is collected, and your code will never be uploaded to the cloud.

Multi-language support

Supports more than 30 programming languages, including mainstream languages such as Go, Python, JavaScript, TypeScript, Java, and C++.

Fast query response

The query response time is usually less than 100 milliseconds, with almost no noticeable delay, providing a smooth development experience.

Zero-configuration startup

You can initialize the project with just one command. It automatically detects the code structure without manual configuration.

Advantages

Runs entirely locally to protect code privacy and security.

No internet connection required, available offline.

Fast response speed with low query latency.

Supports natural language queries without the need to remember specific function names.

Automatically indexes without manual maintenance.

Open source and free, can be customized and extended.

Limitations

Alpha version, may have stability issues.

Requires local installation of Ollama and models, which takes up disk space.

Indexing a large code library for the first time takes time.

Currently mainly supports macOS and Linux, with limited Windows support.

Requires the Claude Code editor to work.

How to use

Installation prerequisites

First, you need to install Ollama, which is a tool for running local AI models. On macOS, you can use Homebrew to install it:

Install AmanMCP

Install AmanMCP via Homebrew:

Initialize the project

Navigate to your project directory and run the initialization command. This will automatically start Ollama, download the necessary AI models, and begin indexing your code:

Restart Claude Code

Restart the Claude Code editor, and it will automatically detect and connect to AmanMCP.

Start asking questions

In Claude Code, ask questions as you normally would, and AmanMCP will automatically provide code context.

Usage examples

Explore a new code library

When you take over a new project, you can use AmanMCP to quickly understand the code structure.

Find a specific function

When you need to modify a certain function but are not sure where it is.

Code review assistance

When reviewing code, understand the context of the relevant code.

Frequently Asked Questions

Does AmanMCP require an internet connection?

Will my code be uploaded to the cloud?

Which programming languages are supported?

How long does it take to index a large code library?

Can the index be shared in a team?

What happens if the Ollama service stops?

Related resources

Official GitHub repository

Source code, issue tracking, and the latest version

Complete documentation

Detailed usage guide, concept explanations, and configuration instructions

Model Context Protocol official website

Understand the technical details of the MCP protocol

Ollama official website

Download and learn about the Ollama local AI model runner

Contribution guide

How to contribute code to AmanMCP

🚀 AmanMCP

Local RAG for your codebase. Zero config. Privacy-first. This tool offers a seamless way to perform hybrid search on your local codebase, with no configuration required and a strong emphasis on privacy.

⚠️ Important Note

This is Alpha Software. Use it at your own risk. Full disclaimer

🚀 Quick Start

Prerequisite: Ollama installed (brew install ollama)

# Install
brew tap Aman-CERP/tap && brew install amanmcp

# Initialize (auto-starts Ollama, pulls model, indexes)
cd your-project && amanmcp init

# Restart Claude Code. Done.

You can then ask Claude: "Search my codebase for authentication"

✨ Features

How It Works

flowchart LR
    subgraph Local["Your Machine (100% Local)"]
        Code[(Codebase)]
        AmanMCP["AmanMCP<br/>BM25 + Vector"]
    end

    Claude["Claude AI"]

    Code -->|index| AmanMCP
    Claude <-->|query| AmanMCP
    AmanMCP -->|context| Claude

    style Local fill:#d5f4e6,color:#000
    style AmanMCP fill:#27ae60,color:#fff
    style Claude fill:#3498db,color:#fff

Key Features

Hybrid search (BM25 + semantic)
AST-aware chunking
Multi-language support
< 100ms query response time

📦 Installation

Method	Command
Homebrew	`brew tap Aman-CERP/tap && brew install amanmcp`
Script	`curl -sSL https://raw.githubusercontent.com/Aman-CERP/amanmcp/main/scripts/install.sh \| sh`
From source	`git clone ... && make install-local`
Offline	`amanmcp init --offline` (BM25-only, no model needed)

💻 Usage Examples

Basic Usage

You can use the following commands to interact with AmanMCP:

Command	Description
`amanmcp init`	Initialize project
`amanmcp search "query"`	Search codebase
`amanmcp doctor`	Troubleshoot issues
`amanmcp status`	Check index health

Full command reference →

Advanced Usage

When connected via MCP, Claude has access to the following tools:

Tool	Purpose
`search`	Hybrid search across codebase
`search_code`	Find functions, classes, types
`search_docs`	Search documentation

You can try asking: "Find the function that handles database connections"

📚 Documentation

Explore the Documentation

Browse our comprehensive documentation organized by topic. Each category highlights key documents to help you quickly find what you need.

Articles - Deep Dives & Insights

Document	Topic	Problem/Question	Key Insight
AI Engineering Guide	Learning Roadmap	How to learn AI/ML engineering efficiently?	80/20 approach - focus on fundamentals that transfer across tools
AI-Native Project Management	Human-AI Collaboration	How to manage projects when AI does most coding?	Human Director / AI Executor model with context management and session workflows
AI-Native Documentation Lessons	Documentation Strategy	How to prevent documentation sprawl?	Internal docs can accumulate faster than they're useful - consolidation strategies matter
Black Box Architecture Case Study	Modular Design	How to build systems that remain maintainable at scale?	Eskil Steenberg's principles - stable interfaces + hidden complexity = decades of durability
Claude Code Search vs AmanMCP Benchmark	Tool Comparison	When to use built-in tools vs specialized search?	Tools are complementary, not competing - each has strengths
Debugging MCP Protocol	Protocol Debugging	Why does MCP integration fail mysteriously?	Stdout contamination breaks protocol - MCP uses stdio for communication
Smaller Models, Better Search	Model Selection	How to choose embedding models under resource constraints?	0.6B models can outperform 8B for specific tasks through quality-focused tuning
Static Embeddings Explained	Fallback Patterns	When should you use static vs dynamic embeddings?	Zero-dependency embeddings enable instant startup and graceful degradation
Zero Friction Lessons	Developer UX	How to achieve "it just works" philosophy?	Every manual step is a leaky abstraction - auto-detection beats configuration

→ Articles documentation overview

Concepts - Core Ideas & Theory

Document	Topic	Problem/Question	Key Insight
Hybrid Search	Search Fundamentals	Why combine keyword and semantic search?	BM25 finds exact matches, vectors find meaning - fusion gets both strengths
MCP Protocol	AI Integration	How does AmanMCP talk to Claude?	Model Context Protocol enables structured AI-tool communication via JSON-RPC
Tree-sitter Guide	Code Parsing	How to parse code without language-specific parsers?	AST-aware chunking preserves semantic boundaries across 30+ languages
Two-Stage Retrieval	Search Optimization	Why search twice instead of once?	Fast filter (candidates) then precise ranking balances speed and accuracy
Vector Search Concepts	Semantic Search	How does semantic search actually work?	Embeddings turn text into numbers that capture meaning geometrically

→ Concepts documentation overview

Guides - Step-by-Step Instructions

Document	Topic	Problem/Question	Key Insight
First-Time User Guide	Getting Started	How do I set up AmanMCP from scratch?	Five steps: install Ollama, install AmanMCP, init project, restart Claude, query
Homebrew Setup Guide	Installation	How to install via Homebrew on macOS?	Homebrew provides automatic updates and dependency management
MLX Setup	Performance	How to get faster embeddings on Apple Silicon?	MLX can be 16x faster than Ollama for local embedding generation
Backend Switching	Configuration	How to switch between Ollama and MLX embeddings?	Simple config change enables comparing backends for your workload
Auto-Reindexing	Workflow	How to keep search index in sync with code changes?	File watching enables real-time incremental updates without manual reindexing
Thermal Management	Optimization	How to reduce CPU heat during indexing?	CPU temperature optimization through batch sizing and concurrency tuning

→ Guides documentation overview

Research - Investigations & Decisions

Document	Topic	Problem/Question	Key Insight
Search Quality Improvement Series	Synthesis	How to solve vocabulary mismatch comprehensively?	Contextual retrieval for vectors + query expansion for BM25 improved pass rate from 60% to 92%
Contextual Retrieval Decision	Search Enhancement	How to bridge vocabulary mismatch between queries and code?	Prepend LLM-generated context to chunks before embedding with pattern fallback
Contextual Retrieval Regression	Quality Analysis	How can enhancements cause regressions?	Small embedding models + contextual prefixes can cluster in embedding space
Query Expansion Asymmetric	Query Processing	Should we expand queries for all search backends?	Expand for BM25 only - expansion helps keyword search but dilutes embeddings
RRF Fusion Rationale	Search Fusion	How to combine BM25 and vector search results?	Reciprocal Rank Fusion (k=60) provides simple, effective combination without training
Vocabulary Mismatch Analysis	Search Quality	Why does semantic search fail for code?	Users say "search function", code says `func Search` - root cause of 40% of failures
Dogfooding Methodology	Quality Validation	How to validate RAG search quality?	Tiered query system with 5 Whys root cause analysis catches semantic gaps
Embedding Models	Model Selection	Which embedding model for code search?	qwen3-0.6b balances quality and resources; code-specialized models improve retrieval 7-8%
Embedding Backend Evolution	Backend Choice	Which embedding backend by default?	Ollama default (lower RAM), MLX opt-in (16x faster) - RAM matters more for development
Embedding Optimization	Performance	How to optimize embedding performance?	MLX vs TEI benchmarking reveals batch size tuning and GPU utilization patterns
Embedding Model Evolution	Evolution	How did our embedding choice evolve?	nomic → Hugot → Qwen3 - each transition taught lessons about tradeoffs
SQLite vs Bleve	Storage Backend	Which BM25 backend for concurrent access?	SQLite FTS5 enables concurrent access (WAL mode) - pure Go, production-proven
Vector Database Selection	Vector Storage	Which vector database for local-first?	USearch → coder/hnsw - pure Go, scales to 300K+ vectors
Specialization vs Generalization	Model Strategy	Should we use specialized or general models?	Specialized models excel in domain but general models provide better fallback
Tree-sitter Chunking	Code Parsing	How to chunk code intelligently?	AST-aware boundaries preserve semantic units - CGO required but worth it
MLX Migration Case Study	Performance Migration	How to plan and execute performance migrations?	Validate before implementing, always have fallback, prefer auto-detection
Observability for RAG	Operations	How to observe RAG systems?	RAG vs agents distinction requires structured logging and search quality metrics

→ Research documentation overview

Contributing - Developer Resources

Document	Topic	Problem/Question	Key Insight
Code Conventions	Code Style	What standards should I follow when contributing?	Error wrapping, resource cleanup, and config-driven behavior are non-negotiable
Testing Guide	Quality Assurance	How do I write tests for AmanMCP?	Table-driven tests with golden files for deterministic validation
TDD Rationale	Development Process	Why does AmanMCP require test-first development?	Tests as specifications prevent rework and enable fearless refactoring

→ View all 3 contributing documents

Reference - Technical Specifications

Document	Topic	Problem/Question	Key Insight
Commands	CLI Usage	What commands are available in AmanMCP?	Six core commands handle initialization, search, health checks, and maintenance
Configuration	Setup	How do I customize AmanMCP behavior?	YAML config controls paths, models, weights, and exclusions
Architecture	System Design	How is AmanMCP structured internally?	Clean separation: MCP layer, search engine, storage, embedding pipeline
Glossary	Terminology	What do technical terms like RRF and HNSW mean?	Quick reference for search, embedding, and MCP concepts

🔧 Technical Details

Roadmap

Status	Feature
Now	Production-ready local RAG for Mac/Linux
Next	Windows support, Rust/Java language support
Later	IDE plugins, remote team search, cloud sync

Contributions are welcome in priority areas.

Privacy

100% Local - No internet required after install
No Telemetry - We don't collect any data
No Cloud - Your code never leaves your machine

Technology

Component	Choice
Language	Go 1.25.5+
Protocol	MCP 2025-11-25
Keyword Search	SQLite FTS5 BM25 (pure Go)
Vector Search	coder/hnsw
Code Parsing	tree-sitter
Embeddings	Ollama (default) / MLX (Apple Silicon)

📄 License

This project is under the Apache 2.0 License - see LICENSE for details.

Disclaimer

AmanMCP is experimental software in active development. By using this software, you acknowledge that it is alpha/beta quality software, accept full responsibility for any issues, and understand that the developers are not liable for data loss, system issues, or other problems.