Skip to content

MCP server

namidb-mcp is a local Model Context Protocol server. It speaks MCP over stdio, so an MCP client (Claude Desktop, Claude Code, and others) launches it as a subprocess and calls its tools. Every tool is read-only; the cypher tool rejects write statements.

It ships in the namidb-v3.3.0-<target> release archive next to the CLI, or builds with cargo install --locked --path crates/namidb-mcp.

Run it

namidb-mcp [--store <URI>] [--vault <DIR>] [--placeholders] [--watch]
FlagDefaultEffect
--store <URI>memory://mcpNamespace to serve. Any storage URI.
--vault <DIR>noneLoad a Markdown vault into the namespace before serving (same mapping as namidb load-vault).
--placeholdersoffWith --vault, create stub notes for links to missing notes.
--watchoffWith --vault, keep the graph in sync with the folder while serving.

Two common setups:

Terminal window
# Load a vault into memory on startup and keep it live:
namidb-mcp --vault ./my-vault --watch
# Serve a namespace you loaded earlier with `namidb load-vault --embed`:
namidb-mcp --store "file:///var/lib/namidb?ns=vault"

Register it with a client

Add it to the client’s MCP server configuration, for example:

{
"mcpServers": {
"namidb": {
"command": "/usr/local/bin/namidb-mcp",
"args": ["--store", "file:///var/lib/namidb?ns=vault"]
}
}
}

Use an absolute path to the binary; clients usually start servers with a minimal PATH.

Tools

The note and tag tools assume the vault schema: :Note nodes, :Tag nodes, and :LINKS_TO, :EMBEDS, :TAGGED and :SUBTAG_OF edges.

ToolArgumentsReturns
list_notes—Every note’s title and path (up to 500).
get_notenoteOne note’s title, path and full Markdown body.
backlinksnoteNotes that link to or embed the note.
neighborsnote, hops (default 1, max 5)Notes within N hops, undirected, via links or embeds.
orphans—Notes with no links or embeds in or out.
searchtextNotes whose title or body contains the substring (case-sensitive, up to 100).
list_tags—Every tag (up to 500).
notes_by_tagtagNotes with the tag or any tag nested under it.
subtagstagImmediate child tags in the nested-tag tree.
tags_ofnoteA note’s tags.
vector_searchquery, k, label, property, whereNotes ranked by semantic similarity; the query is embedded with the model used at load time.
hybrid_searchquery, k, label, property, lexical_weight, semantic_weight, whereKeyword and semantic results fused with Reciprocal Rank Fusion.
graph_algorithmalgorithm, label, edge_types, k, damping, max_iterations, source, targetRuns wcc, scc, pagerank, degree, betweenness, triangle_count, label_propagation, louvain or shortest_path over the subgraph of a label.
cypherqueryAny read-only Cypher statement.

Note names match leniently: case and - / _ / space differences are ignored, and a title or a path works as well as the file name.

vector_search and hybrid_search need note embeddings. A vault loaded with --vault gets them automatically; for a namespace served with --store, load it with namidb load-vault --embed (see CLI). The query is embedded with the same embedder, so use the same embedder configuration for loading and serving.

Check it by hand

MCP is newline-delimited JSON-RPC on stdin/stdout, so you can probe the server without a client:

Terminal window
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"backlinks","arguments":{"note":"Project X"}}}' \
| RUST_LOG=error namidb-mcp --vault ./my-vault
{"id":1,"jsonrpc":"2.0","result":{"capabilities":{"tools":{}},"protocolVersion":"2024-11-05","serverInfo":{"name":"namidb-mcp","version":"3.3.0"}}}
{"id":2,"jsonrpc":"2.0","result":{"content":[{"text":"[\n {\n \"path\": \"sub/Idea.md\",\n \"title\": \"Idea\"\n }\n]","type":"text"}],"isError":false}}