digup-mcp

Search the files that DigUp has indexed, directly from Codex, Hermes Desktop or another MCP client. For example: “Use DigUp to find my notes about knowledge management, then show the matching passages and file paths.”

Works on macOS and Linux, with the original public DigUp application or a compatible CLI installation. A private fork is not required.

Русское руководство пользователя: как пользоваться DigUp MCP в Codex.

Using Hermes Desktop? Follow the local-index walkthrough. You do not need to install Codex.

What you need, and why

There are three separate parts:

The adapter is written in Python. The instructions below use uv to install Python and keep the adapter's dependencies in a separate environment; you do not need a separate Python installer or a manual MCP SDK installation.

Your MCP client ── MCP ── digup-mcp ── DigUp search-service ── DigUp engine/model/index

Installing this adapter alone does not index your files. First set up DigUp, then install the adapter and connect it to your chosen client. If DigUp already searches your files, skip to step 2.

Related MCP server: mcp-memory-search

Install

1. Install DigUp and prepare its index

On a Mac: open DigUp's releases, download the Mac .dmg, open it, and drag DigUp.app into Applications. The current upstream Mac application requires Apple Silicon and macOS 14 or later. Original DigUp 0.6.2 has been tested with this adapter.

On a Linux desktop: download the appropriate Linux package from DigUp's releases and follow its Linux installation instructions. For a Debian/Ubuntu package, use the downloaded .deb; keep the packaged helper and its libraries together. Do not install Debian's unrelated program named digup. For a VPS without a desktop, see the headless setup below.

Then, in DigUp:

1. Open the application.

2. Select the folders you want to search, such as Documents or your Obsidian vault.

3. Let DigUp download its model and index those folders. Its initial model download is about 865 MB; indexing time depends on the amount and type of content.

4. Search for a file you know is in a selected folder. Confirm that DigUp finds it before continuing.

This prepares the data MCP will search. You can keep using your existing DigUp installation and index; there is no need to build a custom desktop app or create a second index for MCP.

2. Install uv and Python

Open Terminal on macOS, or a terminal on Linux. Run the official uv installer:

curl -LsSf https://astral.sh/uv/install.sh | sh

Close and reopen the terminal so it picks up the installed command. Then run:

uv --version
uv python install 3.12

The first command should print a uv version. The second installs the Python runtime that will run this adapter; it does not replace your system Python. See uv's Python guide. If uv is already installed, you can skip its installer.

3. Download and install digup-mcp

Download digup-mcp as a ZIP and extract it. Open a terminal in the extracted digup-mcp-main folder. For example, if you extracted it in Downloads:

cd "$HOME/Downloads/digup-mcp-main"

Use your actual extraction location if it is different. If you already use Git, you can instead run git clone https://github.com/karzaev/digup-mcp.git and cd digup-mcp.

From the folder containing pyproject.toml and constraints.txt, run:

uv tool install --python 3.12 --constraints constraints.txt .

The final . means “install the package from this folder.” uv builds the adapter and installs its dependencies in an isolated tool environment. constraints.txt keeps those dependencies at the project's recorded versions. The installed program works independently of the extracted source folder.

If uv reports that its command directory is missing from your PATH, run uv tool update-shell and reopen the terminal. Then check:

digup-mcp --help

You should see the adapter's options. This confirms installation; verify an actual search after connecting Codex or Hermes Desktop. Do not leave a bare digup-mcp running in a terminal: it waits for an MCP client to send requests and does not open a search window.

Connect Codex

This is step 4. Choose the desktop settings or CLI option below; you only need one. Codex will start the adapter automatically when it needs it.

Through the desktop application

First, print the full path to the installed adapter:

printf '%s/digup-mcp\n' "$(uv tool dir --bin)"

Copy the result, for example /Users/yourname/.local/bin/digup-mcp on a Mac or /home/yourname/.local/bin/digup-mcp on Linux. Then open Settings → MCP servers → Add server and enter:

Save, restart the MCP connection and start a new chat. The local adapter does not need a server URL or API key. For the client-specific controls, see the official Codex MCP documentation.

Through the Codex CLI

If you already use codex in a terminal, register the installed adapter with:

codex mcp add digup -- "$(uv tool dir --bin)/digup-mcp"
codex mcp get digup

The second command should show an enabled digup server and the installed command path. It checks registration, not whether a document can be found. Start a new Codex session for the next step.

If codex is not installed, either use the desktop settings above or install the CLI using the official setup instructions. That setup also explains signing in. This MCP connection is local to the computer running Codex; configuring it does not expose another machine's files.

Connect Hermes Desktop to your local index

This walkthrough is for Nous Research's Hermes Desktop on macOS or Linux. Each person uses their own DigUp installation and index on their own computer. The adapter's supported platforms remain macOS and Linux, even though Hermes itself also offers other platforms.

1. Install Hermes Desktop and choose the local agent

If Hermes Desktop is not installed, download it from the official product page and follow its installation and onboarding guide. Finish the provider/model setup so you can send an ordinary chat message. Existing Hermes users can keep their setup.

Use the local gateway/connection and the profile you want to search from. In recent versions, connection choices are under Settings → Gateways. A Desktop window on your laptop can also control an agent on a VPS or in Hermes Cloud; that agent cannot run your laptop's adapter or read its local index automatically. This walkthrough keeps Hermes, DigUp and the adapter on the same computer.

2. Prepare your own DigUp index

Follow Install DigUp and prepare its index: download the original DigUp, select your folders, wait for its model download/indexing, then find a known file in DigUp itself. If your existing installation already finds that file, reuse it. Do not copy another person's index or create a second one for Hermes.

3. Install the adapter

Follow Install uv and Python, then Download and install digup-mcp. These are the shared installation steps; skip Connect Codex. No Codex installation, Codex account or skill is needed for Hermes MCP search.

On the same computer, open a terminal and print the installed adapter's full path:

printf '%s/digup-mcp\n' "$(uv tool dir --bin)"

Copy the result. It will typically look like /Users/yourname/.local/bin/digup-mcp on macOS or /home/yourname/.local/bin/digup-mcp on Linux. Use your own printed path, not these example usernames.

4. Add the local MCP server in Hermes Desktop

In current Hermes Desktop, open Capabilities → Connectors. In Configuring:, select the same local connection and profile as your chat, then choose Add your own. The dialog is called Connect to a custom MCP. Older releases may place MCP servers in Settings; the terminal alternative below also works with the shared Hermes configuration. Enter:

Click Save and check that the server is enabled. This connection uses a local executable, so there is no MCP server URL or additional API key to enter. Do not paste the printf command or digup-mcp --help into the Command field. If your DigUp executable, index or models use custom locations, add --binary, --index and --models with their actual paths as arguments; see Configure DigUp paths.

Terminal alternative: if you prefer the Hermes CLI, run the following instead of adding the same server again in the GUI. Use the same local Hermes profile as Desktop:

hermes mcp add digup --command "$(uv tool dir --bin)/digup-mcp"
hermes mcp test digup

For a named profile, put --profile your-profile immediately after hermes in both commands. If digup already exists, inspect/edit that entry instead of creating a duplicate. The terminal and Desktop share Hermes settings. The test checks the MCP connection; the document search in step 6 verifies the index and text retrieval. See the official Hermes MCP command reference.

5. Load the tools in your chat

Start a new Hermes Desktop chat on that local connection/profile, or use /reload-mcp in a running chat. Check the server's tools: DigUp exposes search, get_passage and status. Hermes registers them as mcp_digup_search, mcp_digup_get_passage and mcp_digup_status; you normally ask for the task in plain language. If Hermes offers a tool-selection checklist, keep all three enabled.

6. Verify a search against a file you know

Ask in Hermes Desktop:

Use DigUp MCP to check the index status, find the document called “Project plan”, and retrieve its matching passage. Show the full file path and say whether semantic search actually ran.

Replace “Project plan” with the known file from step 2. Expand the tool activity and confirm that Hermes called DigUp's search and passage tools. Compare the returned path and text with your original document. A connected server or an answer written without a tool call is not a successful search check.

meaning: true in the search reply confirms semantic search. If it returns meaning: false with a warning, Hermes should report keyword-only results and the reason. The first search after idle time may take longer. Once this works, ask ordinary questions such as “Use DigUp to find my notes about…” or “Search my PDFs for…”.

You can close the DigUp window when searching the existing index. Let DigUp keep indexing in the background when you want it to pick up new or changed files. Searching does not create an index or start a model download.

If the tools do not appear, check that the entry is enabled on the local connection and the same profile as the chat, then reload MCP or start a new chat. For a missing helper/index or a missing file, check the DigUp paths and troubleshooting table. Hermes does not provide access to a colleague's index merely by installing this adapter.

For the client-side behavior, see the official Hermes MCP guide. The current custom-server UI is also available in the public Hermes Desktop source.

Try your first search

This is step 5. In a new Codex chat, ask:

Use DigUp to find a document called “Project plan”. Show its path and retrieve the matching passage.

Replace “Project plan” with the name or distinctive words from a file you found in DigUp in step 1. Successful verification means Codex used the DigUp search tool, returned the expected file, then retrieved its text with get_passage. Ask whether semantic search actually ran: meaning: true in the search reply confirms it; meaning: false with a warning means the response used words only.

After that, use ordinary requests such as “Find my notes about…”, “Search only PDF documents”, or “Find the code that retries a failed request”. The Russian user guide has more examples.

You can close the DigUp window for searches against the existing index. Keep its indexing process running when you want new and changed files to be picked up automatically. Docker is not required for this setup.

Optional skill: a short search command

Install the included DigUp skill to select this search workflow without repeating “use DigUp” in each request. It uses the same MCP tools; installing the skill does not install or connect MCP. Complete the adapter setup above first. The skill is included in this repository/ZIP, separately from the Python package.

Run the following commands from the extracted repository folder. If a digup skill already exists at the destination, review it before replacing it; the copy command can overwrite its files.

Install the skill in Codex

Copy it to your personal skills folder, available across local projects on macOS and Linux:

mkdir -p "$HOME/.agents/skills"
cp -R skills/digup "$HOME/.agents/skills/"

The installed copy is independent of the extracted repository. Codex detects new skills automatically; if it does not appear, start a new chat or restart Codex. No change to config.toml is needed for the skill itself.

In the desktop app, type / and select digup from the enabled skills, or type $ and select DigUp. Then add your request, for example:

$digup Find notes about knowledge management and show the matching passages.

Codex CLI also supports $digup, or /skills followed by selecting the skill. See the official desktop slash-command reference and skill installation guide.

Install the skill in Claude Code

Claude Code uses its own personal skills folder:

mkdir -p "$HOME/.claude/skills"
cp -R skills/digup "$HOME/.claude/skills/"

The same SKILL.md works in both clients. If DigUp MCP is not yet connected to Claude Code, register the installed adapter for your local projects:

claude mcp add --transport stdio --scope user digup -- "$(uv tool dir --bin)/digup-mcp"
claude mcp get digup

Custom DigUp paths can be added after the adapter executable, as described in Configure DigUp paths. Start a new Claude Code session if the connection or skill does not appear, check /mcp, then invoke:

/digup Find notes about knowledge management and show the matching passages.

See the official Claude Code skills and MCP setup instructions. This personal installation is for local Claude Code; it does not install the skill in Claude web, Cowork or cloud sessions.

In either client, try a known indexed file and ask for its passage to verify the complete workflow. You can request PDFs or source code, but the skill cannot add a folder/vault filter: the current MCP searches the whole index. Selecting returned paths from one folder is not an exhaustive search of that folder.

Linux without a graphical session

This section starts with a working DigUp CLI and its native libraries already installed on the VPS. This adapter does not supply that engine. A public Linux package may provide its helper at /usr/lib/DigUp/helper/digup; the helper can run without opening the graphical shell.

For a public source build, follow the upstream project's native dependency instructions, then build only the CLI with swift build -c release --product digup. That is a build command, not a complete installation: keep the required native libraries with the executable. Copying a developer-build executable alone can break library discovery.

After you have a working CLI, prepare its model and index. In the example below, replace /absolute/path/to/digup with your real executable and /absolute/path/to/notes with the folder you want to index:

digup_cli=/absolute/path/to/digup
digup_data="${XDG_DATA_HOME:-$HOME/.local/share}/digup"
"$digup_cli" download-model --to "$digup_data/Models"
DIGUP_MODELS="$digup_data/Models" "$digup_cli" index /absolute/path/to/notes --index "$digup_data/index"
DIGUP_MODELS="$digup_data/Models" "$digup_cli" search "words from a known note" --index "$digup_data/index" --json

Install this adapter with steps 2–3, then use this connection command instead of the default one in step 4:

codex mcp add digup -- "$(uv tool dir --bin)/digup-mcp" \
  --binary "$digup_cli" --index "$digup_data/index" --models "$digup_data/Models"

Run it in the same terminal where you set digup_cli and digup_data, or substitute their full paths. Codex, MCP and the index all run on that Linux machine. No graphical session is needed; this package does not provide a network MCP endpoint to a different machine's index.

Configure DigUp paths

For a standard Mac installation, the adapter finds /Applications/DigUp.app/Contents/Helpers/digup automatically (also checked under ~/Applications). It uses the existing Application Support index and model directories. For a custom location, pass these options as server arguments in the desktop settings or after the command in codex mcp add:

Options take precedence over environment variables. Without XDG_DATA_HOME, Linux uses ~/.local/share. Linux discovery also checks /opt/digup/bin/digup, /usr/lib/DigUp/helper/digup, /usr/local/lib/DigUp/helper/digup and a helper beside a discovered digup-shell installation. If another program called digup is on PATH, set --binary explicitly. Different package layouts may need explicit index/model paths as well.

Troubleshooting

Compatibility and implementation

The engine must provide search-service with the JSON ready handshake and search, text, status and reload operations. The adapter checks the handshake on its first tool call. It uses the official Python MCP SDK and the existing DigUp service; it does not implement another indexer, read SQLite directly or download its own model. DigUp's service may maintain its normal logs, caches and database schema, as when used by the application.

Original macOS DigUp 0.6.2 is runtime-tested below. Compatible public source builds and forks can use the same adapter without rebuilding it with the desktop app. An App Store edition would need to expose the compatible helper and accessible data paths; such packaging has not been tested here and its availability is not assumed.

Tools

• search(query, limit=10, code=false, kinds=null, meaning=true) searches the entire existing main index, or the separate code index with code=true. It returns the engine's paths, excerpts, segment IDs, scores and page/time/line coordinates. meaning in the reply indicates whether semantic matching actually ran. A warning identifies keyword-only fallback when semantic matching was requested. kinds accepts doc, pdf, image, screenshot, audio, and video for the main index.

• get_passage(segment_id, code=false) asks DigUp for indexed text. Use a segment ID from search and the same code value. Images/audio may have no text, and indexed text can lag the source file.

• status() returns DigUp's existing index counts and encoder state. vectors and code_vectors are currently loaded-vector counts, so zero while idle does not prove that the disk index is empty.

Search requests ask DigUp to reload its view of the index before searching. The existing service controls the model's lifetime. Adapter diagnostics and engine diagnostics go to stderr; stdout is reserved for the SDK's MCP transport.

Obsidian and local data

The adapter can search only what DigUp indexed. A Git-backed Obsidian vault may be skipped by affected DigUp versions because .git marks a code project. That is an indexer issue: fixing it and indexing the omitted notes is separate from installing this adapter. A fork with that fix can be used without changing the adapter.

Index each computer's local copy of a Git-synchronized vault on that computer. Paths and indexes are local; this package does not synchronize SQLite databases. Models, indexes, retrieved passages and user notes are never part of the package or this repository. Retrieved passages returned to an MCP client enter that client's conversation context.

Verified builds

On 2026-10-22, MCP 0.1.1 was tested with the original public DigUp 0.6.2 macOS release, build 13: its bundled helper indexed three synthetic notes in a fresh index, then the installed MCP passed SDK initialization, tool discovery, status, two semantic searches at normal defaults, and source-matching passage retrieval. No custom DigUp build or private fork was used in that check. Nine adapter tests passed, including the regression for the explicit whole-index scope required by DigUp 0.6.2.

On 2026-10-21 a compatible development build (upstream base 7db9537, app metadata 0.6.1, build 12) was tested:

• macOS on Apple Silicon, Swift 6.4, Python 3.14: installed /Applications/DigUp.app helper, existing main/code indexes, semantic search and source passage retrieval. A real Git-backed Obsidian note was indexed and found via CLI, the installed MCP wheel, and Codex's MCP tool calls.

• Ubuntu 22.04.5/aarch64 in Docker, Swift 6.4.1, Python 3.12.15: three synthetic Git-backed vault notes without .obsidian were indexed by the shared CLI. The Linux MCP package searched that index with meaning=true and returned a source-matching passage. Codex on the Mac invoked that Linux MCP/engine through a local container transport; no Codex credentials or personal notes were copied into Linux.

• Eight adapter tests passed on each platform. The Linux paraphrase CLI check used --zgate 0 because its tiny three-document corpus cannot reach the default semantic z-score gate; MCP used V60 coffee at normal defaults.

App Store editions and original Linux release packages have not been runtime-tested here. If a code index is first created after the MCP service starts, restart MCP to detect it.

The Hermes Desktop walkthrough was checked against the official Hermes documentation and current public UI source on 2026-10-22. It describes standard STDIO compatibility; a live Hermes Desktop connection has not been tested here.

Development and release

src/digup_mcp/ contains discovery, the process transport and SDK tool definitions. Tests use a fake process speaking the real DigUp protocol and an official MCP SDK client. They do not index or read personal files.

For development, from a checkout:

uv sync --locked
uv run --locked python -m unittest discover -s tests -v
uv build

This creates a development environment, runs the tests and builds the wheel/source archive in dist/. These steps are not required for the normal installation above. To distribute an already-built wheel:

uv tool install --python 3.12 --constraints constraints.txt dist/digup_mcp-0.1.1-py3-none-any.whl

uv.lock records the development environment; constraints.txt exports its runtime dependency versions for tool installation. The package also pins MCP SDK 1.30.0. After changing the lock, regenerate the constraints with:

uv export --frozen --no-dev --no-emit-project --no-hashes --format requirements.txt --output-file constraints.txt

Before claiming a real engine/platform combination is verified, test CLI indexing/search, MCP initialization, semantic search and passage retrieval against that installed engine and record the actual build and platform. Do not infer semantic success from a valid connection or a keyword-only response.

The MCP adapter is independently versioned. Release compatibility follows the engine's process protocol; desktop updates need no adapter change while that protocol remains compatible. Upstream protocol changes require an adapter test/update rather than a rewrite of DigUp's search logic.

License

MIT, the same license used by the upstream DigUp project. DigUp itself is installed separately.