# rag-mcp

> rag-mcp is an open-source MCP server for knowledge and memory. Scoped hybrid search and grounded answers over local files for coding agents. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, Linux, self-hosted
- **Repository:** https://github.com/masihmoafi/rag-mcp
- **MCP Registry name:** io.github.MasihMoafi/rag-mcp
- **Categories:** [knowledge and memory](https://ai-powered.com/categories/knowledge-and-memory), [files and documents](https://ai-powered.com/categories/files-and-documents), [developer tools](https://ai-powered.com/categories/developer-tools)
- **Listing updated:** 2026-11-18

## About

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.

## Features

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

## Install

### Claude Code (Terminal)

```sh
claude mcp add rag-mcp --env OPENROUTER_API_KEY='<OPENROUTER_API_KEY>' -- uvx ragmcp-cli
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "rag-mcp": {
      "command": "uvx",
      "args": [
        "ragmcp-cli"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "rag-mcp": {
      "command": "uvx",
      "args": [
        "ragmcp-cli"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "rag-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "ragmcp-cli"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "rag-mcp": {
      "command": "uvx",
      "args": [
        "ragmcp-cli"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "rag-mcp": {
      "command": "uvx",
      "args": [
        "ragmcp-cli"
      ],
      "env": {
        "OPENROUTER_API_KEY": "<OPENROUTER_API_KEY>"
      }
    }
  }
}
```

## Tools

- `query_knowledge_base`: Answers a question from a scoped document or folder.

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

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/rag-mcp
