Markdown

You run a lightweight MCP server that indexes local Markdown files and lets you query them with natural language. It combines semantic search, keyword matching, and graph-based retrieval to deliver concise answers with source references, while watching for file changes so your index stays up to date.

How to use

Start either the stdio MCP server for direct editor integrations or the HTTP API for development and integrations. The server exposes a single tool you can use from your MCP client: search and synthesize answers from your Markdown documents.

Using the stdio mode, you connect through a local IPC channel suitable for editors like VS Code. Start it with the command uv run mcp-markdown-ragdocs mcp and you will be able to issue query_documents requests through the MCP channel. The server scans your Markdown files, builds hybrid indices, and watches for file changes to refresh results in real time.

Using the HTTP API, you enable REST-style queries from any HTTP client. Start it with uv run mcp-markdown-ragdocs run and access endpoints at http://127.0.0.1:8000. This mode exposes a query_documents endpoint for programmatic queries and streaming variants for real-time feedback.

How to install

Prerequisites: Python 3.13+ is required to run the server.

Clone the project repository and install dependencies, then start the server in either stdio or HTTP mode.

Commands you will run in order:

Configuration and notes

Configure the server with a TOML file named .mcp-markdown-ragdocs/config.toml placed in your project directory or in your global config at ~/.config/mcp-markdown-ragdocs/config.toml. The configuration controls host, port, document paths, index storage, weighting for search strategies, and other behavior.

Configuration examples

[server]
host = "127.0.0.1"
port = 8000

[indexing]
documents_path = "~/Documents/Notes"
index_path = ".index_data/"

[search]
semantic_weight = 1.0
keyword_weight = 1.0
recency_bias = 0.5
rrf_k_constant = 60
min_confidence = 0.0
max_chunks_per_doc = 0
dedup_enabled = false

CLI and API endpoints

You can query documents directly from the CLI with the MCP query tool, or use the HTTP API endpoints for integration. The server also supports streaming query results via Server-Sent Events for real-time feedback.

Standard query endpoint: POST to http://127.0.0.1:8000/query_documents with a JSON payload containing your query string. Streaming endpoint: POST to http://127.0.0.1:8000/query_documents_stream with the same payload to receive SSE events.

Troubleshooting and tips

If you don’t see results or indexing seems stalled, check that your document path is correct and that the server has permission to read those files. Ensure the index storage directory exists or is creatable by the running process. Restart the server after changing the configuration to rebuild indices.

For mono-repo setups, you can place a shared config in the repository root to apply the same indexing rules across multiple projects. The server automatically rebuilds indices when configuration changes.

Available tools

query_documents

Search indexed Markdown documents using hybrid retrieval (semantic, keyword, and graph-based strategies) and return a synthesized answer with source documents.