rag-mcp
Scoped hybrid search and grounded answers over local files for coding agents
- Pricing
- Open source
- Platforms
- CLI, Linux, self-hosted
- Runs
- Locally
- Version
- 0.3.0
- Listing updated
- today
Similar MCP servers
About rag-mcp
rag-mcp is an open-source MCP server for knowledge and memory. It runs locally on your machine and is started by your AI client.
The problem it targets is a trade-off coding agents face: open files one at a time and miss things, or dump a repository into context and waste it. rag-mcp moves retrieval and answer writing behind a single scoped call, so the agent receives a short answer, not the source tree. Its README marks the project as beta and verified on Linux with Python 3.13.
Search is scoped to an explicit file, a narrow folder or a saved workspace. It fuses exact-word BM25 with embeddings, then reranks. With no account and no key, only exact-word search is on and questions return the best passages with file and line numbers. Meaning search needs an embedding provider, and written answers come from a signed-in Codex or an OpenRouter key.
The README spells out what leaves your machine: answer text and selected evidence go to Codex or OpenRouter, source files and indexes stay local. It reads PDF, HTML and notebooks, with optional office formats.
Install
Run in a terminal
claude mcp add rag-mcp --env OPENROUTER_API_KEY='<OPENROUTER_API_KEY>' -- uvx ragmcp-cliAdd to claude_desktop_config.json
{
"mcpServers": {
"rag-mcp": {
"command": "uvx",
"args": [
"ragmcp-cli"
],
"env": {
"OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"rag-mcp": {
"command": "uvx",
"args": [
"ragmcp-cli"
],
"env": {
"OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"rag-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"ragmcp-cli"
],
"env": {
"OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"rag-mcp": {
"command": "uvx",
"args": [
"ragmcp-cli"
],
"env": {
"OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"rag-mcp": {
"command": "uvx",
"args": [
"ragmcp-cli"
],
"env": {
"OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
}
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
OPENROUTER_API_KEYOpenRouter key for answer synthesis and hosted reranking; exact-word search works without it
Tools this server provides (1)
Taken from the project documentation; the running server may differ.
- query_knowledge_base
- Answers a question from a scoped document or folder.
What it does
- Scoped retrieval
- Searches one file, a narrow folder or a saved workspace.
- Hybrid ranking
- Combines BM25 and embeddings, fuses ranks, then reranks.
- Works without a key
- Exact-word search and passage results need no account.
- Written answers
- Uses Codex sign-in or an OpenRouter key to write grounded answers.
- CLI and MCP
- The rag command and the MCP server share workspaces.
- Agent setup
- rag connect registers it with Claude, Codex, Copilot or Gemini.
Good for
- Ask a repository question without loading it into context
- Find which doc answers a policy question
- Search a folder of PDFs for a passage
- Give a coding agent a safe, scoped retrieval tool
Pricing
Open source
rag-mcp FAQ
Does it need an API key?
Not for exact-word search. Answers need Codex sign-in or an OpenRouter key.
What leaves my machine?
Questions and selected evidence go to the answer provider; files and indexes stay local.
Which platforms are verified?
Linux with Python 3.13.
How do I connect Claude Code?
claude mcp add rag -s user -- rag mcp
Is rag-mcp free?
Yes. rag-mcp is open source, so you can use and self-host it for free.
How do I add rag-mcp to Claude Code?
Run this command in your terminal: claude mcp add rag-mcp --env OPENROUTER_API_KEY='<OPENROUTER_API_KEY>' -- uvx ragmcp-cli
What are the best alternatives to rag-mcp?
The closest alternatives to rag-mcp are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.


