Local-first MCP knowledge server

Turn any folder into agent knowledge.

Search code, documents, PDFs, audio, and video from any MCP client. Every answer points back to the exact file, line, page, or moment.

Start in two minutes View on GitHub

Open sourceOne Go binaryCloud or fully local

~/notes — dir2mcp

$dir2mcp up✓ scanned 3 files · 12 chunks✓ embeddings local · nomic-embed-text✓ MCP ready · http://127.0.0.1:49172/mcp$dir2mcp ask "When is the budget meeting?"The quarterly budget meeting is Thursday at 10:00in room 4B. [meetings.md:L1-L6]Citations[1] meetings.md · lines 1–6$

Built for trust

Not another chat-with-docs black box.

dir2mcp is deployment infrastructure for agents: small, inspectable, and grounded in the source material you control.

01 / Provenance

Answers you can verify

Citations identify the actual source span—not just a filename. Open the cited lines, PDF page, image region, or exact seconds of a recording.

file:L12-L24page:700:18:04–00:18:17

02 / Coverage

Nothing fails silently

Status and doctor commands name skipped files, unsupported formats, extraction failures, and partial transcripts—plus what to do next.

03 / Privacy

Local means local

Run embeddings and answers with Ollama, extraction with docling, and speech with self-hosted Whisper. A doctor check reports any third-party egress.

04 / Multimodal

One corpus, every kind of source

Code and Markdown sit beside office files, PDFs, images, transcripts, and time-coded recognition events. Agents use the same small tool surface across all of them.

codemarkdownPDFofficeaudiovideo

From folder to MCP

Your knowledge, online for agents in minutes.

The server becomes available while indexing continues. Connect Claude, Cursor, or any Streamable HTTP MCP client.

Point

Run dir2mcp up inside the directory you want to serve.

Index

Content is extracted, chunked, embedded, and linked to source spans.

Connect

Install the endpoint into your MCP client and start asking questions.

brew install dirstral/tap/dir2mcp && dir2mcp up

A real local run

No cloud account. No staged answer.

This recording uses Ollama with local embeddings and a local Qwen model over three plain Markdown notes.

Terminal demonstration of dir2mcp indexing three notes and answering a question with a line citation — The demo can be reproduced from the public repository with `make demo`.

Measured, not hand-waved

The answer path is benchmarked end to end.

The published benchmark starts from empty state, indexes a public corpus, asks 120 questions through MCP, and scores answers and citations without a model judge.

75%

of answerable responses contain a gold answer.

98.7%

file-level precision for inline citations.

100%

of answerable questions include the gold passage in structured citations.

Published local-model run, 24 September 2026: SQuAD 2.0 subset, nomic-embed-text and Qwen 2.5 7B. Results vary by corpus and model.Read the method and raw results.

Choose your path

From first question to production endpoint.

Start locally, understand the security boundary, then deploy only as far as your use case requires.

01 · Five minutes

Your folder already knows the answer.

Give your agent a safe, cited way to find it.

Start locally Explore the code