Install the binary

On macOS or Linux, use the signed Homebrew formula. The lean package is the fastest start; it can use local docling, a docling server, or cloud OCR when document extraction is needed.

brew tap dirstral/tap && brew install dirstral/tap/dir2mcp

Confirm that the binary is available:

dir2mcp version

Windows

Download the amd64 or arm64 zip fromGitHub Releases. Windows runs the server in the foreground; use a second terminal for commands.

Choose where models run

Fully local with Ollama

Pull one embedding model and one chat model, then run dir2mcp in the folder you want to query. On first use, the setup wizard detects Ollama and lets you choose the installed models.

ollama pull nomic-embed-text && ollama pull qwen2.5:7b

cd ~/notes && dir2mcp up

One Mistral cloud key

Mistral can provide embeddings and answers from one credential, with OCR and speech capabilities available for matching source types. Keep the key in the environment or OS keychain—never in the YAML configuration.

export MISTRAL_API_KEY=your_key_here && dir2mcp up

For a persistent encrypted credential, rundir2mcp config set-secret MISTRAL_API_KEY and enter it at the hidden prompt.

Ask the first question

The server indexes incrementally. You can validate the answer path from a second terminal while indexing continues:

dir2mcp ask "What are the key decisions in this folder?"

A grounded answer includes inline source tags and a structured citation list. Use dir2mcp status to see indexed, pending, skipped, and failed content.

Connect an MCP client

Run the install command from the same served folder. It reads the daemon URL and token from the local state directory and updates only its own client entry.

Client	Command	Afterwards
Claude Code	`dir2mcp install claude-code`	Start a new session.
Cursor	`dir2mcp install cursor`	Open Settings → MCP.
Claude Desktop	`dir2mcp install claude`	Restart the app.

Check the installed integration with dir2mcp doctor <client>. Stop the server with dir2mcp down; the index remains under.dir2mcp/ and resumes incrementally next time.

Next steps

Review the security boundary before exposing an endpoint.
Choose a deployment shape for Docker, tunnels, or remote corpora.
Read the complete configuration reference for extraction, providers, retrieval, and media.