Viberag MCP Server | Codebase RAG, Semantic Search for Coding Agents

v0.8.0 is now available

██╗   ██╗██╗██████╗ ███████╗██████╗  █████╗  ██████╗ 
██║   ██║██║██╔══██╗██╔════╝██╔══██╗██╔══██╗██╔════╝ 
██║   ██║██║██████╔╝█████╗  ██████╔╝███████║██║  ███╗
╚██╗ ██╔╝██║██╔══██╗██╔══╝  ██╔══██╗██╔══██║██║   ██║
 ╚████╔╝ ██║██████╔╝███████╗██║  ██║██║  ██║╚██████╔╝
    ╚═══╝  ╚═╝╚═════╝ ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝

Viberag is a free, open-source MCP server for semantic, hybrid, and full-text codebase search. Powerful Coding Agent Search Tools for Massive Codebases.

$ npm install -g viberag

COPY

Get Started

Powering Your Favorite Agents

Claude Code Cursor Gemini CLI JetBrains IDEs OpenAI Codex OpenCode Roo Code VS Code Copilot Windsurf Zed and others...

Unlock Deep Context

Supercharge Your Prompts

Stop pasting file contents. Stop hoping your agent guesses the right filename.
Invoke the magic words use viberag and your coding agent have access to a variety of semantic codebase search tools find everything.

Token Efficient Navigation

Instead of dumping files into context, viberag returns structured results with metadata and stable IDs grouped by type (definitions, usages, files, code blocks with line numbers). Drill into relevant code only when needed using follow-up tools like get_symbol_details and read_file_lines.

Exhaustive Search

Prevent missing context. Whether planning a feature or refactoring, viberag ensures your agent is aware of every relevant and related reference, catching edge cases and "code islands" that simple keyword searches miss.

Developer Query → viberag MCP Tool Use

Intent-Based Retrieval

Ask naturally. Your coding agent selects the right viberag MCP search tool for the job.

You ask:

"How does this app handle payments?"

intent: concept

Agent calls:

codebase_search(query: "payment processing billing checkout", intent: "concept")

Finds StripeService.ts, Invoice.go, and checkout_flow.py—even though none contain the word "payments."

You ask:

"I need to update the UserAuthenticator class"

intent: definition

Agent calls:

codebase_search(query: "UserAuthenticator class", intent: "definition")

Returns the declaration at auth/UserAuthenticator.ts:24, not the 47 files that reference it. Fuzzy matching handles typos—UserAuthenticater still finds it.

You ask:

"What will break if I rename processOrder?"

find_references

Agent calls:

codebase_search(query: "processOrder", intent: "definition") → find_references(symbol_id)

Returns 12 call sites, 3 imports, 2 type annotations—grouped by file and ready for systematic updates.

You ask:

"Where does 'Invalid API key format' come from?"

intent: exact_text

Agent calls:

codebase_search(query: "Invalid API key format", intent: "exact_text")

Full-text search with fuzzy matching. Finds validation.ts:47 even if the agent's query has minor typos.

You ask:

"Find other rate limiters like this one"

intent: similar_code

Agent calls:

codebase_search(query: "<rate limiter code snippet>", intent: "similar_code")

Code pattern matching surfaces throttler.go and quota_enforcer.py—same structure, different names.

Five retrieval intents. One tool. Fuzzy matching handles typos in symbol names.
Override auto-routing with explicit intent parameter when needed.

Why Keywords Aren't Enough

In large polyglot monorepos, concepts are scattered. Standard agents "guess" file and function names using grep-like logic. Viberag understands meaning.

Standard Agent

Query:

"How do we validate user permissions?"

Guesses filenames: "permission.ts", "validate.js"

Greps for "validateUser"

Misses: auth_middleware.go (Golang backend)

Misses: Guard.py (Python service)

Incomplete Context

Agent hallucinates or asks you to open files manually.

With Viberag

Query:

"Use viberag to find how permissions are validated."

Vector Search matches concept "Validation" ≈ "Guard"

Cross-language retrieval (TS, Go, Python)

src/middleware/AuthGuard.ts 92% match

pkg/auth/rbac.go 89% match

Full Semantic Context

Agent sees the actual logic, regardless of keywords.

Zero Config Needed

Automated Setup & Indexing

Viberag handles the heavy lifting. Run the initialization wizard to configure your preferred embedding model (local or cloud) and let the file watcher keep your index in sync.

$ viberag

Launch CLI

/init Wizard

Interactive CLI command to set up embeddings, download models, and index your codebase for the first time.

/mcp-setup

Automatically configures Claude Code, Cursor, and VS Code config files to connect to the viberag MCP server.

Agent-Aware Watch Mode

Your agent automatically starts viberag's watch mode. It detects code changes and instantly updates the search index, so your agent always has the latest context without manual re-indexing.

viberag — -zsh — 80x24

How it Works

Seamless integration from disk to context.

Parse & Embed

Tree-sitter parses your code into semantic chunks. Embeddings are generated locally or via API and stored locally in LanceDB. Everything is stored on your machine for fast, secure, private access.

Auto-Launch & Watch

The Editor / agent automatically starts viberag which starts watching for file changes. Every change automatically triggers updates to the search index. The Agent has access to its search tools and can monitor the indexing status.

Fast Hybrid Retrieval

Viberag executes local semantic search, full-text search, and even fuzzy keyword matching search, and returns agent-friendly results with stable follow-up handles.

Exposed MCP Tools

Viberag exposes these powerful tools to your connected AI agents.

codebase_search

Primary

Your starting point for code exploration. Routes queries to the right search strategy.

concept definition usage exact_text similar_code

See intent routing in action

Follow-up Tools

get_symbol_details

Fetch complete code, signature, docstring, and decorators for a symbol.

find_references

Find all call sites, imports, and type annotations across the codebase.

get_surrounding_code

See neighboring symbols and related chunks around a search result.

read_file_lines

Read exact source code at specific line numbers.

Utility Tools

help Usage guide for all tools

build_index Build or update the index

get_status Check index and daemon status

get_watcher_status Check auto-indexing status

cancel_operation Cancel indexing or warmup

Precision Parsing

Syntax-Aware Chunking

Viberag uses Tree-sitter to parse code into an Abstract Syntax Tree (AST). It creates semantic boundaries—keeping functions, classes, and scopes intact—so the embedding model captures the complete logical unit.

Tree-sitter parsers active

JavaScript

.js, .mjs, .cjs

TypeScript

.ts, .mts, .cts

TSX

.tsx

Python

.py

.go

Rust

.rs

Java

.java

.cs

Swift

.swift

Kotlin

.kt, .kts

PHP

.php

Flexible Embedding Models

Choose between complete privacy or state-of-the-art cloud performance. Viberag adapts to your security requirements.

Offline

Locally Generated Embeddings

Local, Free, No API Keys, (slow)
Code & Natural Language understanding
Zero data egress

Frontier

API Embedding Providers

Connect to OpenAI, Gemini, or Mistral for state-of-the-art semantic understanding.

Fastest generation speed
Highest Semantic Understanding
Still very cheap

Index Control

Control What Gets Indexed

Viberag respects .gitignore automatically. For non-git projects (or extra exclusions), add a .viberagignore file in your project root. It uses the exact same pattern syntax as .gitignore.

.viberagignore

# build outputs
dist/
build/

# local artifacts
coverage/
tmp/

# generated bundles
**/*.min.js