1. Conduid
  2. AI
  3. Amanmcp
MCP server · AI

Amanmcp

by · github.com/Aman-CERP/amanmcp

AmanMCP is a local-first RAG MCP server for developers - providing hybrid search (BM25 + semantic) over codebases for AI assistants like Claude Code and Cursor.

Unclaimed Apache-2.0 bm25mcphnswhybrid-searchmcp-serverclaude-codegolangaicursor
InstallView source
58Fair

Scored 3 days ago · breakdown

About Amanmcp

Amanmcp is an MCP server published by Aman-CERP in the AI category: amanMCP is a local-first RAG MCP server for developers - providing hybrid search (BM25 + semantic) over codebases for AI assistants like Claude Code and Cursor.

The repository has 3 stars and 0 forks, with the last commit 3 months ago. Recent commit activity is the strongest signal that reported issues will get attention.

Install

From source
git clone https://github.com/Aman-CERP/amanmcp

This server has no ConduID identity, so agent calls to it are not receipted. Pin the version you install and review the source before granting it credentials.

Tools (3)

searchHybrid search across codebase

Parameters not published.

search_codeFind functions, classes, types

Parameters not published.

search_docsSearch documentation

Parameters not published.

Ask AI

✦

Ask AI about Amanmcp

Powered by Claude · Grounded in docs

I know everything about Amanmcp. Ask me about installation, configuration, usage, or troubleshooting.

Security checks

  • ✓README presentThe repository ships documentation.
  • ✓License declaredUsable under a stated license.
  • !Scoped permissionsDoesn't declare a permission scope. Assume it can do anything its process can.

3 checks have not been run yet.

Releases

v0.16.0v0.16.0 · 22 Jun 2026Changelog Other 530b95294a9660ad0836d10283e9d3e035798d82: sync: update from development repository (@nirajkvinit) Installation Homebrew (macOS) - Recommended brew tap Aman-CERP/amanmcp brew install --cask amanmcp Install Script (macOS…
v0.15.0v0.15.0 · 21 Jun 2026Changelog Other 3d687d48fbdd1847613feb32374999edaf60a6f7: sync: update from development repository (@nirajkvinit) 863b1af989db6e5ef4e46f2a42d6d4aabc889a66: sync: update from development repository (@nirajkvinit) Installation Homebrew…
v0.14.0v0.14.0 · 20 Jun 2026Changelog Other b1c51df347c270cdef207fa307a1f42f11c95faa: sync: update from development repository (@nirajkvinit) Installation Homebrew (macOS) - Recommended brew tap Aman-CERP/amanmcp brew install --cask amanmcp Install Script (macOS…
v0.12.1v0.12.1 · 3 May 2026Changelog Other b936fe9782ef77e8f62d9b9bb76c17c2edf00c54: sync: update from development repository (@nirajkvinit) Installation Homebrew (macOS) - Recommended brew tap Aman-CERP/amanmcp brew install --cask amanmcp Install Script (macOS…

README

AmanMCP

Local RAG for your codebase. Zero config. Privacy-first.

Version Go

Alpha Software - Use at your own risk. Full disclaimer

Quick Start

Prerequisite: Ollama installed (brew install ollama)

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

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

# Restart Claude Code. Done.

Ask Claude: "Search my codebase for authentication"

What It Does

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 | < 100ms queries

Essential Commands

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

Full command reference →

What Claude Can Do

When connected via MCP, Claude has these tools:

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

Try: "Find the function that handles database connections"

Documentation

I want to... Go here
Get started step-by-step Quick Start Guide
See all CLI commands Command Reference
Configure settings Configuration
Use MLX (Apple Silicon) MLX Setup
Understand how search works Hybrid Search Guide
Contribute code Contributing

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

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 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

Install Options

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

Technology

Component Choice
Language Go 1.25.9+
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)

Contributing

See CONTRIBUTING.md for development setup and guidelines.

Priority areas: Language support, Windows support, performance.

License

Apache 2.0 License - see LICENSE

Disclaimer

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

Acknowledgments

Model Context Protocol by Anthropic | coder/hnsw | Ollama | tree-sitter | Qwen

Made with care by the AmanERP Team · "It just works."

README copy captured when this server was indexed; it may lag the repository. The original is authoritative.

Questions

About Amanmcp

How do I install Amanmcp?

No package has been published for this server, so install it from source: clone the repository and follow its README.

Is Amanmcp safe to use with an AI agent?

Its trust score is 58 out of 100 (fair). It passes 2 of the 3 static security checks run so far; the failures are listed above. It has no ConduID identity yet, so agent calls to it are not receipted.

Is Amanmcp still maintained?

Yes — the latest release is v0.16.0 (22 Jun 2026), and the last commit was 3 months ago. The repository has 3 stars.