TinyRAG
Provides optional semantic retrieval through an OpenAI-compatible Embedding API for vector-based similarity search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TinyRAG what does the knowledge base contain about RAG?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
TinyRAG
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
uvpreferred;pipis supportedGit
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.pyExpected 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.pyActivate .venv first when required by the operating system.
Add Knowledge
Put UTF-8
.txtfiles indata/raw/.Run a query or restart the MCP server.
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 |
| Retrieve relevant context and return a lightweight grounded answer or excerpt |
| Return source chunks for the calling agent to reason over |
| 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-smallNever 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.pyOperational Constraints
Supported source format:
.txtonlyTransport: 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/ordata/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 termsCompletion Check
Before reporting installation complete, verify all of the following:
uv run python -m unittest discover -s tests -vanduv run python scripts/eval.pypass.data/raw/contains the intended documents.The MCP configuration uses an absolute and existing
cwd.The MCP host can see
query_knowledge_base,search_relevant_chunks, andlist_documents.No secret or private generated file is staged in Git.
Available Tools
3 toolslist_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
Scored across 3 tools
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.
All tool names follow a consistent verb_noun pattern using snake_case: query_, list_, search_. The naming is predictable and clear.
Three tools is an appropriate size for a focused RAG server, covering retrieval and listing without unnecessary bulk.
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
Related MCP Connectors
Make your knowledge agent-ready. One MCP endpoint, 5 connectors, 3 search modes.
Ask your own documents and get answers that cite the source passage. Workspace knowledge bases over MCP for Cursor, Claude and any MCP client.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
A second brain for your AI agent. Shared memory for your team's AI agents, plus public and private knowledge bases — works with ChatGPT, Claude, Cursor and any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables 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 npm653MIT
- FlicenseAqualityDmaintenanceA 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-
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to manage, upload, chunk, and semantically search local documents through MCP tools and a REST API, with a built-in web dashboard and optional Gemini-powered AI search.1MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to semantically search and read curated local markdown knowledge bases through MCP, with optional CLI and dashboard tooling.MIT