A Model Context Protocol (MCP) server that provides a local-first RAG engine for your markdown documents. This server uses a file-based Milvus vector database to index your notes, enabling Large Language Models (LLMs) to perform semantic search and retrieve relevant content from your local files.
[!NOTE] This project is in active development. The API and implementation are subject to change. We are exploring future enhancements, including a potential port to an Obsidian plugin for seamless vault integration.
🎯 Key Features
✅ Local-First & Private: All your data is processed and stored locally. Nothing is sent to a third-party service for indexing.
✅ Semantic Search for Markdown: Go beyond simple keyword search. Find document sections based on conceptual meaning.
✅ MCP Compatible: Integrates with any MCP-supported host application like Claude Desktop, Windsurf, or Cursor.
✅ Simple Tooling: Provides two straightforward tools (index_documents and search) for managing and querying your knowledge base.
⚙️ How It Works
The server operates in two main phases, exposing its functionality through MCP tools.
-
Indexing:
- The
index_documentstool is called with a path to your markdown files. - The server reads the documents, splits them into logical chunks (e.g., by headings), and converts each chunk into a vector embedding.
- These embeddings, along with their metadata (original text, file path), are stored in a local Milvus vector database.
- You can run it in two modes:
- Full Reindex (force_reindex=True): Clears and rebuilds the entire index from scratch.
- Incremental Update (force_reindex=False, default): Automatically detects and re-indexes only changed files by comparing them against a tracking log. Deleted or modified chunks are pruned and replaced to keep the index up-to-date.
- Recursive Indexing (recursive=False, default): Recursively indexes all subdirectories.
- The
-
Searching:
- When you ask a question in a host application, it uses the
searchtool. - The server converts your query into a vector embedding.
- It then performs a similarity search against the Milvus database to find the most semantically relevant document chunks.
- The results are returned to the LLM, providing it with the context needed to answer your question accurately.
- When you ask a question in a host application, it uses the
🛠️ Available Tools
-
index_documents- Description: Indexes Markdown documents for semantic search. Converts each file into structured vector chunks and inserts them into the Milvus database.
- Incremental Indexing: Automatically reindexes only changed files unless force_reindex=True is passed.
- Arguments:
directory(string, optional): The path to the folder containing .md files. Defaults to current directory.force_reindex(boolean, optional): If True, clears and rebuilds the full index. Defaults to False.recursive(boolean, optional): If True, recursively indexes all subdirectories. Defaults to False.
-
search- Description: Searches the indexed documents using semantic similarity.
- Arguments:
query(string, required): Your natural language query.limit(integer, optional): Max number of chunks to return (default is usually 5–10).
🚀 Installation & Setup
This server requires UV (for running the Python server).
Step 1: Get the Server Code
Clone this repository to your local machine:
git clone https://github.com/Zackriya-Solutions/MCP-Markdown-RAG.git
Step 2: Configure Your Host App
Configure your MCP host application (e.g., Windsurf, Claude.app) to use the server. Add the following to your settings file:
{
"mcpServers": {
"markdown_rag": {
"command": "uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/MCP-Markdown-RAG",
"run",
"server.py"
]
}
}
}
Note: Replace
/ABSOLUTE/PATH/TO/MCP-Markdown-RAGwith the absolute path to where you cloned this repository.
Note: The first run will take a while and the same for the first indexing, as it needs to download the embedding model(~50MB).
📈 What's Next? (Roadmap)
We are actively working on improving the server. Future plans include:
- Performance Optimization: Improve indexing by encoding inputs in batches, which should better manage CPU usage.
- Flexible Embedding Models: Add support for other embedding models, such as the
BGEM3-largemodel for potentially higher accuracy. - Obsidian Plugin: Explore creating a dedicated Obsidian plugin for a fully integrated experience.
🐛 Debugging
You can use the MCP inspector to debug the server directly. Run the following command from the repository's root directory:
npx @modelcontextprotocol/inspector uv --directory /ABSOLUTE/PATH/TO/MCP-Markdown-RAG run server.py
🤝 Contributing
Contributions are welcome! Please feel free to open an issue or submit a pull request.
🙏 Acknowledgments
- The Model Context Protocol for the open standard that makes this possible.
- The Milvus Project for the powerful open-source vector database.
Metadata
Release files for iflow-mcp_zackriya-solutions-mcp-markdown-rag 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_zackriya_solutions_mcp_markdown_rag-0.2.0.tar.gz | 2.5 MB | Without provenance | Details for iflow_mcp_zackriya_solutions_mcp_markdown_rag-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_zackriya_solutions_mcp_markdown_rag-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_zackriya_solutions_mcp_markdown_rag-0.2.0-py3-none-any.whl |
Total release size: 2.5 MB
Release files / iflow_mcp_zackriya_solutions_mcp_markdown_rag-0.2.0.tar.gz
| Download URL | iflow_mcp_zackriya_solutions_mcp_markdown_rag-0.2.0.tar.gz |
|---|---|
| Size | 2.5 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bd1c060ad7745220c96fa4dddee502f4f9aa49eda5042eb83135392bcc24d145
|
|
BLAKE2b-256 checksum How to use checksums |
e868dbb78933a246340b2af964c87c9c9518e9baeae58ab53dc99b400070d718
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_zackriya_solutions_mcp_markdown_rag-0.2.0-py3-none-any.whl
| Download URL | iflow_mcp_zackriya_solutions_mcp_markdown_rag-0.2.0-py3-none-any.whl |
|---|---|
| Size | 12.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
04bd26b484558000152ab9aa73adb9fa110b288630e8176b6faae59577a8bdd3
|
|
BLAKE2b-256 checksum How to use checksums |
87b2243e9eabb5e81ac1de1be3b1061611108f872546869abdcedffdcc3f2cf7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_zackriya-solutions-mcp-markdown-rag 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.