ObsidianMap

MCP server that turns an Obsidian vault into a mind-map graph for Claude Code. Claude can search, traverse, link, and create concept notes from inside the conversation. Code repos collapse to a single opaque node so they don't pollute the graph.

Install

You need: Node.js 20+, git, and Claude Code.

git clone https://github.com/alfarom256/ObsidianMap.git
cd ObsidianMap
npm install
npm run build

Configure your vault

Copy the example config into your Obsidian vault root and rename it to .mindmap.json:

cp .mindmap.example.json /path/to/your/vault/.mindmap.json

Open that file and tweak opaqueFolders — these are globs of folders that should collapse to a single node instead of being traversed. Typical values: Projects/*, Code/*, **/node_modules.

Register with Claude Code

claude mcp add obsidian-mindmap -- node /absolute/path/to/ObsidianMap/dist/index.js /path/to/your/vault/.mindmap.json

On Windows, use forward slashes in the paths (e.g. C:/Users/you/ObsidianMap/dist/index.js).

Verify

In Claude Code, run /mcp. You should see obsidian-mindmap connected. Try:

Search my vault for nodes related to graph theory.

Tools exposed to Claude

Read: search_nodes, get_concept, neighbors, path_between, subgraph, suggest_gaps Write: create_concept, link_concepts, update_concept, merge_concepts, reindex

Semantic gap detection (optional)

@huggingface/transformers is installed automatically by npm install. To enable gap detection, set embeddings.enabled: true in .mindmap.json and restart Claude Code. The first call to suggest_gaps downloads ~30 MB of model weights and caches them locally. Then ask Claude:

What concept gaps are in my vault?

It returns concept pairs that are semantically related but not yet linked.

Config reference

{
  "vaultPath": ".",                       // vault root, relative to this config file
  "opaqueFolders": ["Projects/*"],        // globs of folders that collapse to single nodes
  "conceptThreshold": {
    "minChars": 200,                      // small notes (below BOTH thresholds) are skipped
    "minOutgoingLinks": 2
  },
  "embeddings": {
    "enabled": false,
    "model": "Xenova/all-MiniLM-L6-v2",
    "similarityThreshold": 0.78
  },
  "watch":  { "enabled": true, "debounceMs": 500 },
  "index":  { "path": ".mindmap-index.json" }
}

Day-to-day notes

• Edit notes in Obsidian as usual; the watcher updates the in-memory graph and the persistent index automatically.
• merge_concepts moves the merged file to <vault>/.trash/ rather than deleting it — recoverable.
• If the graph drifts (e.g. mass renames outside Obsidian), ask Claude to call the reindex tool, or delete .mindmap-index.json and restart the MCP.