Skip to main content
Glama

TinyRAG

CI License: MIT

Your agent already has an LLM. TinyRAG gives it a private knowledge base through MCP.

No Docker. No vector database. No mandatory API key. Add your .txt documents to data/raw/; TinyRAG automatically chunks and indexes them, then exposes the relevant source text to your agent through MCP.

Zero RAG configuration: the defaults work out of the box, with optional semantic retrieval when you need it.

You do not need to install or configure anything yourself. Give this repository to an agent with terminal access, and it can set up TinyRAG for you.

Give this repository to your agent and tell it:

Install TinyRAG, add my text documents, run its evaluation, and configure it as a local stdio MCP server. Do not commit secrets or private documents.

Repository: https://github.com/spacecat398/TinyRAG-MCP


你的 Agent 已经拥有 LLM,TinyRAG 通过 MCP 为它提供一个私有知识库。

无需 Docker,无需向量数据库,也不强制要求 API Key。把 .txt 文档放入 data/raw/,TinyRAG 会自动切块并建立索引,再通过 MCP 把相关原文提供给你的 Agent。

RAG 零配置:默认设置开箱即用,需要时再开启语义检索。

你不需要亲自安装或配置任何东西。把这个仓库交给拥有终端权限的 Agent,它会替你完成 TinyRAG 的安装和接入。

把这个仓库地址发给你的 Agent,并告诉它:

安装 TinyRAG,添加我的文本文档,运行项目评估,并将它配置为本地 stdio MCP 服务器。不要提交密钥或私人文档。

仓库地址:https://github.com/spacecat398/TinyRAG-MCP


Agent Instructions

This section is written for AI agents that install, configure, or operate TinyRAG.

Objective

Install TinyRAG as a local MCP server and expose the user's UTF-8 .txt documents as searchable knowledge. Prefer the smallest working configuration. Do not add Docker, a vector database, or an LLM dependency unless the user explicitly requests one.

Requirements

  • Python 3.12 or newer

  • uv preferred; pip is supported

  • Git

  • A host that can launch local stdio MCP servers

Install

git clone https://github.com/spacecat398/TinyRAG-MCP.git
cd TinyRAG-MCP
uv sync
uv run python -m unittest discover -s tests -v
uv run python scripts/eval.py

Expected test result: all unit tests pass. Expected evaluation result: 3 passed, 0 failed.

If uv is unavailable:

python -m venv .venv
python -m pip install -r requirements.txt
python -m unittest discover -s tests -v
python scripts/eval.py

Activate .venv first when required by the operating system.

Add Knowledge

  1. Put UTF-8 .txt files in data/raw/.

  2. Run a query or restart the MCP server.

  3. TinyRAG automatically rebuilds data/processed/ when source file names, modification times, or chunk settings change.

Do not commit private documents unless the user explicitly approves it. The included sample documents may be removed.

Configure MCP

Use the following local stdio server definition. Replace cwd with the absolute repository path on the current machine.

{
  "mcpServers": {
    "tinyrag": {
      "command": "uv",
      "args": ["run", "python", "rag_app/mcp_server.py"],
      "cwd": "/absolute/path/to/TinyRAG-MCP"
    }
  }
}

Windows paths may use forward slashes, for example C:/Users/name/TinyRAG-MCP.

Configuration file names and locations vary by MCP host. Adapt the object to the host's schema without changing the command, arguments, or working directory. TinyRAG uses stdio; do not configure it as an HTTP server.

Available Tools

Tool

Purpose

query_knowledge_base(question)

Retrieve relevant context and return a lightweight grounded answer or excerpt

search_relevant_chunks(question, top_k=3)

Return source chunks for the calling agent to reason over

list_documents()

List indexed source documents

For agentic workflows, prefer search_relevant_chunks when the calling agent should produce the final answer itself.

Retrieval Modes

TinyRAG works without an API key:

  • Default: local keyword retrieval

  • Optional: semantic retrieval through an OpenAI-compatible Embedding API

  • Fallback: keyword retrieval when the Embedding API is unavailable

To enable semantic retrieval, create .env from .env.example:

TINYRAG_ENABLE_REMOTE_EMBEDDINGS=true
OPENAI_API_KEY=
OPENAI_BASE_URL=https://api.openai.com/v1
EMBEDDING_MODEL=text-embedding-3-small

Never commit .env. Remote embeddings stay disabled unless TINYRAG_ENABLE_REMOTE_EMBEDDINGS=true is set explicitly. When enabled, document chunks and queries are sent to the configured API endpoint. Inform the user before enabling a remote endpoint for private data.

Direct Query

uv run python scripts/query.py "What does the knowledge base say about RAG?"

Interactive mode:

uv run python scripts/query.py

Operational Constraints

  • Supported source format: .txt only

  • Transport: local MCP stdio only

  • Generation: lightweight rule/excerpt generation, not a general-purpose LLM

  • Storage: JSON cache under data/processed/

  • Default chunk size: 500 characters

  • Default overlap: 80 characters

  • Default retrieval count: 3 chunks

The calling agent is expected to handle general reasoning and answer generation. TinyRAG focuses on loading, caching, and retrieving local context.

Safety Rules

  • Never expose or commit .env.

  • Never commit .venv/ or data/processed/.

  • Treat files in data/raw/ as potentially private.

  • Do not silently enable a remote Embedding API.

  • Do not delete user documents when rebuilding the cache.

  • Keep paths relative to the repository except for the MCP host's required absolute cwd.

Important Files

rag_app/mcp_server.py   MCP stdio entry point
rag_app/pipeline.py     retrieval pipeline
rag_app/retriever.py    keyword and embedding retrieval
rag_app/cache.py        automatic local cache
data/raw/               user source documents
data/processed/         generated cache, ignored by Git
scripts/eval.py         smoke evaluation
scripts/query.py        command-line query tool
.env.example            optional embedding configuration
CHANGELOG.md            release notes and upgrade changes
LICENSE                 MIT license terms

Completion Check

Before reporting installation complete, verify all of the following:

  1. uv run python -m unittest discover -s tests -v and uv run python scripts/eval.py pass.

  2. data/raw/ contains the intended documents.

  3. The MCP configuration uses an absolute and existing cwd.

  4. The MCP host can see query_knowledge_base, search_relevant_chunks, and list_documents.

  5. No secret or private generated file is staged in Git.

Available Tools

3 tools
list_documentsA

列出知识库中的所有文档。

Inputs: no named parameters. Returns: result

query_knowledge_baseA

从本地知识库中查找与问题最相关的内容并生成答案。

Args:
    question: 用户问题,如"小明的宠物叫什么?"

Inputs: question (required). Returns: result

search_relevant_chunksA

搜索与问题最相关的知识片段(不经过生成器,返回原文)。

Args:
    question: 搜索关键词
    top_k: 返回片段数量(默认 3)

Inputs: question (required), top_k. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 3 tools

    Disambiguation3/5

    query_knowledge_base and search_relevant_chunks both search the knowledge base for relevant content, differing only in whether the response is generated or raw chunks. An agent might select the wrong one if not attentive. list_documents is clearly distinct.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case: query_, list_, search_. The naming is predictable and clear.

    Tool Count5/5

    Three tools is an appropriate size for a focused RAG server, covering retrieval and listing without unnecessary bulk.

    Completeness3/5

    The tools cover querying and listing but lack document management (add, update, delete). This is a notable gap for a knowledge base server, though the core retrieval workflow is present.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to search, deep-read, and build knowledge bases from Markdown, PDF, DOCX, and PPTX documents via MCP tools for retrieval, document navigation, and ingestion.
      15 npm
      653
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      A local-first document retrieval engine that mounts as an MCP tool for agents to index files, search for relevant passages, and let the agent's own LLM answer.
      4
      -