dir2mcp
Point it at a folder. Ask questions about what is inside, and get answers that cite the exact file and lines, or the exact seconds of a recording.
dir2mcp indexes a directory (code, Markdown, PDFs and office documents, audio
and video) and serves it over MCP, the
protocol Claude, Cursor and other AI clients use to reach tools and data. It is
one Go binary with its state in .dir2mcp/ next to your files. It runs fully
local if you want: embeddings and answers can come from Ollama or any
OpenAI-compatible server, and dir2mcp doctor verifies that nothing leaves the
machine.
This is a real run against an Ollama server (nomic-embed-text and
qwen2.5:7b-instruct-q4_K_M), with no cloud account. make demo records it
again from assets/demo/demo.tape.
Try it in two minutes
brew tap dirstral/tap
brew install dirstral/tap/dir2mcp # the full name trusts only this formula
cd ~/notes # any folder you want to ask about
On Windows, get the zip from Releases instead; see Windows for what works there and what does not.
Fully local, no account (with Ollama):
ollama pull nomic-embed-text && ollama pull qwen2.5:7b
dir2mcp up # the first run asks how to run the models: pick "Locally with Ollama"
The setup finds Ollama, lists its models and writes .dir2mcp.yaml. To script
it (no terminal), write the same file yourself:
cat > .dir2mcp.yaml <<'EOF'
providers:
local:
kind: openai
base_url: http://127.0.0.1:11434/v1
embed_text_model: nomic-embed-text
embed_code_model: nomic-embed-text
chat_model: qwen2.5:7b
model:
embed: {provider: local}
chat: {provider: local}
EOF
dir2mcp up
Or with one cloud key (Mistral is the default; OpenAI and Gemini work too):
export MISTRAL_API_KEY=...
dir2mcp up
Then ask from the terminal, or hand the folder to Claude Code, Cursor or Claude Desktop:
$ dir2mcp ask "When is the budget meeting?"
The quarterly budget meeting is on Thursday. [notes.md:L1-L3]
Citations
[1] notes.md chunk=2 span=L1-L3
$ dir2mcp install claude-code # Claude Code: start a new session, then ask about the folder
$ dir2mcp install cursor # Cursor: the server shows in Settings > MCP
$ dir2mcp install claude # Claude Desktop: restart it, then ask about the folder
dir2mcp status shows what was indexed, and names every file it skipped with
the reason. dir2mcp down stops the server; up resumes incrementally.
What makes it different
-
Answers cite spans, not files. A citation names a line range for text and code, a page for PDFs, and a time range for audio and video.
open_filereturns exactly the cited span. -
Coverage is honest. A file it could not read, a passage in a language the speech model does not cover, or a window of broken transcription is recorded with its reason.
dir2mcp statusanddir2mcp doctorname it; nothing is dropped silently. -
Any provider, one capability at a time. Embedding, extraction, speech, answers and reranking bind independently, so you can mix providers:
A provider turns on when its credential is present. There is no separate enable flag.
-
Fully local if you want. docling for extraction, and Ollama, vLLM, llama.cpp, LM Studio or TEI for embeddings and answers.
dir2mcp doctorreports whether any configured provider is a third-party host. -
Media and video. Transcripts and recognized on-screen events become time-anchored, filterable annotations, so an answer can cite a moment and a client can play exactly that moment.
Connect a client
Run these in the folder that dir2mcp up serves:
Each install replaces only its own entry and keeps your other servers.
dir2mcp doctor <client> checks the entry, and dir2mcp uninstall <client>
removes it. Details: connect an MCP client.
Install
docs/install.md has the lean and full tracks, the Nix service modules and the Windows details.
MCP tools
What a citation carries lists the fields of a time span.
Configure
The first dir2mcp up in a terminal runs a setup wizard and writes
.dir2mcp.yaml. dir2mcp config init runs it again, and dir2mcp config print shows the settings in force. Keys go in the environment, in
.env.local, or in the OS keychain (dir2mcp config set-secret), never in the
YAML file.
docs/configuration.md is the full reference. It includes a fully local, no-egress setup, self-hosted endpoints, document extraction, reranking, and which files are indexed.
Common commands
All commands: docs/cli.md.
Benchmark
An end-to-end benchmark runs the real binary on a public corpus (120 questions
from SQuAD 2.0, CC BY-SA 4.0) with local models only (nomic-embed-text and
qwen2.5:7b). On the published run, 75% of the answers contain the gold
answer, 98.7% of the inline citations name the correct file, and dir2mcp
declines 25% of the questions that the corpus cannot answer. With
rag.verify_faithfulness: true it declines 75%, and 67.5% of the answers
contain the gold answer. Method, raw results and how to run it again:
bench/README.md.
Security
- The server listens on
127.0.0.1by default, with a bearer token. --publicrequires auth unless you also pass--force-insecure.- The server does not index its own config or
.envfiles. dir2mcp support-bundlealways removes credentials, so you can attach it to a public issue.
docs/security.md has the full defaults. To report a vulnerability, read SECURITY.md.
Documentation
Guides in this repo:
- Install, configuration, commands, MCP tools, security
- Tunnels and reverse proxies, dual-machine deployment (GPU host, corpus on NFS or S3), optional x402 request gating
The normative specification lives in the
dirstral-spec submodule:
SPEC, VISION,
ECOSYSTEM, and the
compatibility matrix.
dirstral-conformance is a
black-box conformance suite for any server that claims the spec, and
dirstral-cli is a terminal client.
Development
make check # the full local gate (never rewrites the tree)
make build # build the dir2mcp binary
make bench-e2e # run the end-to-end benchmark
make demo # record assets/demo.gif again
Read CONTRIBUTING.md before you open a pull request. Contributor and agent guides: AGENTS.md, CLAUDE.md.
License
MIT. See LICENSE.