Skip to main content
Glama

RAG-MCP

A Model Context Protocol server that gives an LLM client searchable access to a local document corpus. It indexes a directory of Markdown and text files with BM25 at startup and exposes four tools over stdio: search, read a passage, read a document, list the corpus.

The retrieval is the whole product. Generation is the client's job, so this server never calls a model and needs no API key.

Quick start

Requires Python 3.11 or newer.

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/python -m pytest          # 67 tests
RAG_CORPUS_DIR=corpus .venv/bin/python -m rag_mcp

Run on its own it will sit waiting for JSON-RPC on stdin, which is correct: an MCP server is launched by its client, not used directly.

Connecting it to a client

Add it to the client's MCP server config. For Claude Desktop that is claude_desktop_config.json; for Claude Code it is .mcp.json in the project.

{
  "mcpServers": {
    "rag-mcp": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "rag_mcp"],
      "env": { "RAG_CORPUS_DIR": "/absolute/path/to/your/docs" }
    }
  }
}

Point RAG_CORPUS_DIR at any directory of notes. The corpus/ directory in this repo holds three documents about MCP and retrieval so the server does something useful the first time it starts.

Related MCP server: doc-rag-mcp

Tools

Tool

Arguments

Returns

search_documents

query, optional top_k (1 to 25)

Ranked passages with chunk id, source file, BM25 score and a snippet centred on the match

get_chunk

chunk_id

The full passage plus its character offsets in the source file

get_document

source

The whole document, truncated with a flag if very large

list_documents

none

Every indexed document with size and chunk count, plus anything that was skipped

Responses are JSON in a text block. Two details are deliberate. Search returns the chunk_id so the model can fetch the exact passage before quoting it, and an empty result set comes back with an explicit note saying nothing matched, rather than as an empty list a model might paper over.

How retrieval works

Tokenising. Lowercase, split on non-word characters, drop tokens shorter than two characters and a small stop list, then strip one trailing plural s. Documents and queries go through the same function, which matters more than it sounds: if the two sides normalise differently, terms silently stop matching and results get quietly worse rather than visibly broken.

Chunking. Documents are split into overlapping windows of 180 words with 40 words of overlap, both configurable. Overlap exists so a fact sitting on a chunk boundary still appears whole in one chunk. Each chunk keeps the character offsets of its span, so any result can be traced back to an exact region of the source.

Ranking. BM25 Okapi, k1 = 1.5, b = 0.75:

idf(t) = ln(1 + (N - df(t) + 0.5) / (df(t) + 0.5))

score(D,Q) = sum over t in Q of
             idf(t) * f(t,D) * (k1 + 1) / (f(t,D) + k1 * (1 - b + b * |D| / avgdl))

k1 controls how fast term frequency saturates, so the tenth occurrence of a word adds far less than the second. b controls length normalisation, so a long document does not win simply by containing more words.

Design decisions

BM25 rather than embeddings. No model download, no vector store, no API key, so the server starts in the time it takes to walk a directory and runs anywhere the client runs. Every score is explainable from the formula, so a surprising ranking is debuggable. The cost is real: BM25 matches words, not meaning, and a query phrased entirely in synonyms will miss. On technical documentation, where the person asking usually shares the vocabulary of the text, that trade is worth taking. It would not be for a corpus of customer emails.

The index is in memory and built once. For a documentation corpus this is a few megabytes and it removes a whole class of failure: no stale index, no vector store to be unreachable. The cost is that changing a file means restarting the server.

Failing loudly at startup. A missing corpus directory exits non-zero instead of serving an empty index. An empty index answers every query with "no results", which reads as a retrieval bug and hides a configuration mistake.

Logging to stderr, always. Stdout carries the JSON-RPC stream. One stray print corrupts the protocol and the client disconnects with a parse error that points nowhere near the cause.

Dispatch separated from transport. tools.py takes a corpus, a tool name and a dict, and returns content. It has no session object in it, so every behaviour is unit-testable without starting a server, and server.py stays pure wiring.

Tests

.venv/bin/python -m pytest -q

67 tests. They cover the tokeniser's normalisation rules, chunk overlap and offset round-tripping, BM25 properties that are easy to get wrong (term frequency saturation, length normalisation, non-negative idf, deterministic tie breaks), corpus building including skipped and non-UTF-8 files, every tool's success and failure path, the server handlers themselves, verifying that a bad tool call comes back as a tool error the model can read rather than a crashed connection, and one end to end test that runs a real client session against the server over in-memory streams. That last one is the only test that catches a mistake in the wiring itself, such as a handler that is never registered or a result shape the client cannot parse.

Built against the 2.x Python SDK, where the low level Server takes its handlers as constructor callbacks rather than decorators and Tool uses input_schema rather than inputSchema. The dependency is pinned to <3 so a future major release cannot silently break it.

CI runs the suite on Python 3.11, 3.12 and 3.13 on every push.

Available Tools

4 tools
get_chunkA

Return the full text of one passage by its chunk id, as returned by search_documents, together with its character offsets in the source file.

Inputs: chunk_id (required).

get_documentA

Return the full text of one indexed document by its source path. Large documents are truncated, and the response says so.

Inputs: source (required).

list_documentsA

List every indexed document with its size and chunk count. Use it to find out what this corpus actually covers before searching.

Inputs: no named parameters.

search_documentsA

Search the indexed corpus for passages relevant to a query and return ranked results with their source file and a snippet. Use this first, then call get_chunk or get_document to read the full text of anything you intend to quote or rely on.

Inputs: query (required), top_k.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 4 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: search returns ranked passages, get_chunk retrieves a specific chunk, get_document retrieves a full document, and list_documents provides an overview. There is no overlap or ambiguity between them.

    Naming Consistency5/5

    All tool names follow the same verb_noun pattern with lowercase and underscores: search_documents, get_chunk, get_document, list_documents. The convention is perfectly consistent.

    Tool Count5/5

    Four tools form a tight, well-scoped set for a RAG server. Each tool earns its place by covering the essential retrieval workflow without redundancy or bloat.

    Completeness5/5

    The tool surface covers the full retrieval lifecycle: discover what's indexed (list_documents), search the corpus (search_documents), read a specific passage (get_chunk), and read the full source (get_document). No obvious gaps exist for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Local-first Markdown vault retrieval for agents. Read-only MCP stdio server exposing search, get, status, and doctor over Obsidian-compatible Markdown with hybrid BM25/vector/wikilink/title retrieval and first-class CJK support.
      11
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Turns any folder of PDFs, markdown, and text files into a local, queryable knowledge base exposed as an MCP server. Enables MCP-compatible agents to semantically search indexed documents, retrieve relevant passages with source and relevance scores, list or reindex documents, and inspect cache and token usage — instead of reading whole files into context.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables BM25 lexical search over a user-provided corpus of CTF writeups or technical documents through an MCP tool, returning relevant results with optional category and solved filters. It can run locally over stdio or as a centralized HTTP service shared by multiple MCP clients.
      MIT
    • A
      license
      Not graded
      quality
      F
      maintenance
      Exposes a stdio MCP server that indexes a markdown vault (such as an Obsidian folder of notes) into SQLite FTS5 and answers BM25-ranked section-level queries, with filters for note type. It also exposes reindexing so notes edited on disk become searchable again, giving coding agents persistent, durable memory across sessions.
      MIT