VIBERAG MCP Server

Free, Open Source, Local / Offline Capable, Container-Free Semantic Search For Your Codebase

VibeRAG is fully local, offline capable MCP server for local codebase search.

• Intent-routed codebase search (definitions/files/blocks/usages)
• Hybrid retrieval (full-text + vector search)
• Explainable results with stable follow-ups (open spans, get symbols, find usages)

VibeRAG automatically indexes your codebase into a local container-free vector database (lancedb). Every time you make a change, the indexes are automatically updated.

Install

npm install -g viberag

Quick Start

# Initialize in your project
cd your-project
viberag

# Run the initialization wizard to configure embeddings, run initial indexing, and automatically configure MCP server integration.
/init

# In addition to allowing Agents to search via the MCP server,
# you can search yourself via the CLI.
/search authentication handler

Example

When using a coding agent like Claude Code, add use viberag to your prompt.

────────────────────────────────────────────────────────────────────
> How is authentication handled in this repo? use viberag
────────────────────────────────────────────────────────────────────

Tip: include "use viberag" in your prompt to ensure your agent will use viberag's codebase search features. Most agents will select MCP tools as appropriate, but sometimes they need a little help with explicit prompting.

Features

• CLI based setup - CLI commands and wizards for setup, editor integration, and configuration
• Agent-first search - Find definitions, entry files, and relevant blocks (not just “chunks”)
• Flexible embeddings - Local model (offline, free) or cloud providers (Gemini, Mistral, OpenAI)
• MCP server - Works with Claude Code, Cursor, VS Code Copilot, and more
• Automatic incremental indexing - Watches for file changes (respects .gitignore + .viberagignore) and reindexes only what has changed in real time
• Cancelable indexing - Supports /cancel and clear status reporting via /status
• Multi-language support - TypeScript, JavaScript, Python, Go, Rust, and more
• Blazing fast - The data storage and search functionality is local on your machine, meaning the full power of your machine can churn through massive amounts of data and execute complex search queries in milliseconds.

How It Works:

Your coding agent would normally use Search / Grep / Find and guess search terms that are relevant. VibeRAG indexes the codebase into a local vector database (based on lancedb) and can use semantic search to find all relevant code snippets even if the search terms are not exact.

When searching for "authentication", VibeRAG will find all code snippets that are relevant to authentication, such as "login", "logout", "register", and names of functions and classes like AuthDependency, APIKeyCache, etc.

This ensures comprehensive search of your codebase so you don't miss important files and features that are relevant to your changes or refactor.

Great for Monorepos

Semantic search is especially useful in monorepos, where you may be trying to understand how different parts of the codebase interact with each other. Viberag can find all the pieces with fewer searches, fewer tokens used, and a shorter amount of time spent searching.

Embedding Models

All options store embeddings and indexed data on your local machine

• Local: You can use a locally run embedding model (Qwen3-Embedding-0.6B) so that nothing leaves your machine. This has a smaller vocabulary and is only recommended for privacy and offline concerns.

• Recommended: API generated embeddings from Gemini, OpenAI, and Mistral are recommended for the largest vocabulary and highest quality semantic meaning.

  • These embeddings are very affordable at ~10 - 15 cents per million tokens.
  • A typical codebase can be indexed for pennies

MCP Server

VibeRAG includes an MCP server that integrates with AI coding tools.

IDE / Agent Setup Wizard

Run /mcp-setup in the VibeRAG CLI for interactive setup. This wizard will attempt to automatically configure your coding agents / editors with viberags MCP server settings.

# Start viberag
$ viberag

# Run the setup wizard (after having initialized with /init)
$ /mcp-setup

# Automatic configuration wizard
╭───────────────────────────────────────────────────────────────╮
│ MCP Setup Wizard                                              │
│                                                               │
│ Select AI coding tool(s) to configure:                        │
│ (Space to toggle, Enter to confirm)                           │
│                                                               │
│ > [x] Claude Code (auto-setup)                                │
│   [ ] Cursor (auto-setup)                                     │
│   [ ] Gemini CLI (global config)                              │
│   [ ] JetBrains IDEs (manual setup)                           │
│   [ ] OpenAI Codex (global config)                            │
│   [ ] OpenCode (global config)                                │
│   [ ] Roo Code (auto-setup)                                   │
│   [ ] VS Code Copilot (auto-setup)                            │
│   [ ] Windsurf (global config)                                │
│   [ ] Zed (global config)                                     │
│                                                               │
│ 1 selected | ↑/↓ move, Space toggle, Enter confirm, Esc cancel│
╰───────────────────────────────────────────────────────────────╯

The wizard can auto-configure project-level configs and merge into global configs.

Manual Setup Instructions

The following sections describe manual MCP server setup configurations for various editors and agents.

claude mcp add viberag -- npx viberag-mcp

{
	"mcpServers": {
		"viberag": {
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

{
	"mcpServers": {
		"viberag": {
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

{
	"mcpServers": {
		"viberag": {
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

{
	"mcpServers": {
		"viberag": {
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

gemini mcp add viberag -- npx viberag-mcp

{
	"mcpServers": {
		"viberag": {
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

{
	"mcpServers": {
		"viberag": {
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

codex mcp add viberag -- npx -y viberag-mcp

[mcp_servers.viberag]
command = "npx"
args = ["-y", "viberag-mcp"]

{
	"mcp": {
		"viberag": {
			"type": "local",
			"command": ["npx", "-y", "viberag-mcp"]
		}
	}
}

{
	"mcp": {
		"viberag": {
			"type": "local",
			"command": ["npx", "-y", "viberag-mcp"]
		}
	}
}

{
	"mcpServers": {
		"viberag": {
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

{
	"mcp": {
		"servers": {
			"viberag": {
				"command": "npx",
				"args": ["viberag-mcp"]
			}
		}
	}
}

{
	"servers": {
		"viberag": {
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

{
	"mcpServers": {
		"viberag": {
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

{
	"context_servers": {
		"viberag": {
			"source": "custom",
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

{
	"context_servers": {
		"viberag": {
			"source": "custom",
			"command": "npx",
			"args": ["viberag-mcp"]
		}
	}
}

Exposed MCP Tools

VibeRAG exposes a small set of agent-centric tools. Backward compatibility with legacy tool names is not provided.

codebase_search

Single entry point with intent routing. Use scope for transparent filters.

• intent: auto|definition|usage|concept|exact_text|similar_code
• Definition-style symbol lookups tolerate small typos via fuzzy (Levenshtein) name matching.
• scope: path_prefix, path_contains, path_not_contains, extension
• explain: include per-hit channels + ranking priors

Example:

{
	"query": "how does authentication work",
	"intent": "concept",
	"scope": {
		"path_prefix": ["src/"],
		"path_not_contains": ["test", "__tests__", ".spec.", ".test."]
	},
	"k": 20,
	"explain": true
}

Follow-ups: get_symbol_details, read_file_lines, get_surrounding_code, find_references.

CLI Commands

VibeRAG includes a CLI for easy execution of initialization, indexing, setup, and other things you may want to manually control outside of agent use.

Data Directory

VibeRAG stores all per-project state (config, index, logs) globally under:

• ~/.local/share/viberag/projects/<projectId>/ (override via VIBERAG_HOME)

No files are written into your repo.

Ignoring Files

VibeRAG uses .gitignore rules to exclude files and folders from indexing. For non-git projects (or for additional ignore patterns), you can create a .viberagignore file in the project root.

• .viberagignore uses the exact same pattern syntax as .gitignore
• It is applied in addition to .gitignore (if present)

Example .viberagignore:

# build outputs
dist/
build/

# local artifacts
coverage/
tmp/

# generated bundles
**/*.min.js

Logs

VibeRAG writes per-service logs with hourly rotation:

• ~/.local/share/viberag/projects/<projectId>/logs/daemon/ - daemon lifecycle and IPC errors
• ~/.local/share/viberag/projects/<projectId>/logs/indexer/ - indexing progress, retries, and batch failures
• ~/.local/share/viberag/projects/<projectId>/logs/mcp/ - MCP server errors
• ~/.local/share/viberag/projects/<projectId>/logs/cli/ - CLI errors

If indexing appears slow or retries are happening, check the latest file under ~/.local/share/viberag/projects/<projectId>/logs/indexer/.

Embedding Providers

Choose your embedding provider during /init:

Local Model - Offline, Free

• Works completely offline, no API key required
• Initial indexing may take time; future updates are incremental
• Works great for code and natural language (docs, docstrings, code comments, etc.)

Cloud Providers - Fastest, Best Quality, Largest Vocabulary

• Gemini - Free tier available, great for getting started
• Mistral - Code-optimized embeddings for technical content
• OpenAI - Fast and reliable with low cost

API keys are entered during the /init wizard and stored globally in ~/.local/share/viberag/secrets/secrets.json (override via VIBERAG_HOME). Project configs store only a key id reference (never the raw API key).

How It Works

1. Parsing - Tree-sitter extracts functions, classes, and semantic chunks
2. Embedding - Code chunks are embedded using local or API-based models
3. Storage - Vectors stored in LanceDB (local, no server required)
4. Search - Hybrid search combines vector similarity + full-text search
5. MCP - AI tools query the index via the MCP protocol

AI Agent Best Practices

VibeRAG works best when AI agents use sub-agents for exploration tasks. This keeps the main conversation context clean and uses ~8x fewer tokens.

Why Sub-Agents?

When an AI calls viberag directly, all search results expand the main context. Sub-agents run searches in isolated context windows and return only concise summaries.

Platform-Specific Guidance

Claude Code

# For exploration tasks, use the Task tool:
Task(subagent_type='Explore', prompt='Use viberag to find how authentication works')

# For parallel comprehensive search:
Task(subagent_type='Explore', prompt='Search auth patterns') # runs in parallel
Task(subagent_type='Explore', prompt='Search login flows')   # with this one

Add to your CLAUDE.md:

When exploring the codebase, use Task(subagent_type='Explore') and instruct it
to use the viberag `codebase_search` tool (and follow-ups like `get_symbol_details` / `read_file_lines`). This keeps the main context clean.

VS Code Copilot

• Use Agent HQ to delegate exploration to background agents
• Background agents can iterate with viberag without blocking your session
• Use /delegate to hand off exploration tasks to Copilot coding agent

Cursor

• Enable Agent mode for multi-step exploration
• Agent mode can orchestrate multiple viberag searches autonomously
• Consider the Sub-Agents MCP server for Claude Code-style delegation

Windsurf

• Cascade automatically plans multi-step tasks
• Enable Turbo Mode for autonomous exploration
• Cascade's planning agent will orchestrate viberag calls efficiently

Roo Code

• Use Architect mode for exploration and understanding
• Boomerang tasks coordinate complex multi-mode workflows
• Each mode (Architect, Code, Debug) can use viberag with focused context

Gemini CLI

• Create extensions that scope viberag tools for specific tasks
• Extensions can bundle viberag with custom prompts for specialized exploration
• Use gemini mcp add viberag then reference in extension configs

OpenAI Codex

• Use Agents SDK to orchestrate viberag as an MCP tool
• Codex can run as an MCP server itself for multi-agent setups
• Approval modes control how autonomously Codex explores

JetBrains IDEs

• Junie agent handles multi-step exploration autonomously
• Claude Agent integration provides sub-agent-like capabilities
• Access viberag through AI Chat with multi-agent support

Zed

• Use External Agents (Claude Code, Codex, Gemini CLI) for exploration
• Set auto_approve in settings for autonomous agent operation
• ACP (Agent Client Protocol) enables BYO agent integration

Quick Lookup vs Exploration

For Platforms Without Sub-Agents

Use a few targeted codebase_search calls with different intents, then follow up with get_symbol_details, read_file_lines, get_surrounding_code, and find_references as needed.

Example sequence:

{"query": "authentication", "intent": "concept", "k": 20}

{
	"query": "login",
	"intent": "definition",
	"k": 20,
	"scope": {"path_prefix": ["src/"]}
}

{"symbol_name": "login", "k": 200}

Troubleshooting

Watcher EMFILE (too many open files)

Large repos can exceed OS watch limits. The watcher honors .gitignore and .viberagignore, but if you still see EMFILE:

• Add more ignores in .gitignore or .viberagignore to reduce watched files.
• Increase OS limits:
  • macOS: raise kern.maxfiles, kern.maxfilesperproc, and ulimit -n
  • Linux: raise fs.inotify.max_user_watches, fs.inotify.max_user_instances, and ulimit -n

Index failures (network/API errors)

If indexing fails due to transient network/API issues:

• Run /status to confirm daemon/index state.
• Re-run /index after connectivity is stable.
• Use /cancel to stop a stuck run, then /reindex if you need a clean rebuild.