Skip to content
MCP server

rag-mcp

Scoped hybrid search and grounded answers over local files for coding agents

Runs locallyStatus and history
Install
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-cli

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

How AIPoweredBot checks servers