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]| Flag | Default | Effect |
|---|---|---|
--store <URI> | memory://mcp | Namespace to serve. Any storage URI. |
--vault <DIR> | none | Load a Markdown vault into the namespace before serving (same mapping as namidb load-vault). |
--placeholders | off | With --vault, create stub notes for links to missing notes. |
--watch | off | With --vault, keep the graph in sync with the folder while serving. |
Two common setups:
# 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.
| Tool | Arguments | Returns |
|---|---|---|
list_notes | — | Every note’s title and path (up to 500). |
get_note | note | One note’s title, path and full Markdown body. |
backlinks | note | Notes that link to or embed the note. |
neighbors | note, hops (default 1, max 5) | Notes within N hops, undirected, via links or embeds. |
orphans | — | Notes with no links or embeds in or out. |
search | text | Notes whose title or body contains the substring (case-sensitive, up to 100). |
list_tags | — | Every tag (up to 500). |
notes_by_tag | tag | Notes with the tag or any tag nested under it. |
subtags | tag | Immediate child tags in the nested-tag tree. |
tags_of | note | A note’s tags. |
vector_search | query, k, label, property, where | Notes ranked by semantic similarity; the query is embedded with the model used at load time. |
hybrid_search | query, k, label, property, lexical_weight, semantic_weight, where | Keyword and semantic results fused with Reciprocal Rank Fusion. |
graph_algorithm | algorithm, label, edge_types, k, damping, max_iterations, source, target | Runs wcc, scc, pagerank, degree, betweenness, triangle_count, label_propagation, louvain or shortest_path over the subgraph of a label. |
cypher | query | Any 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:
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}}