ObsidianMap

# 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**. ```bash 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`: ```bash 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 ```bash 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.* ## One-shot setup with the included skill Instead of editing `.mindmap.json` by hand, install the bundled Claude Code skill and let it walk you through configuration: ```bash mkdir -p ~/.claude/skills/configure-obsidian-map cp SKILL.md ~/.claude/skills/configure-obsidian-map/SKILL.md ``` Then in Claude Code: `/configure-obsidian-map`. It inventories the vault, proposes which folders should be opaque / excluded / indexed as concepts, and writes the config when you confirm. ## Tools exposed to Claude **Tree navigation:** `tree`, `children`, `parent`, `ancestors`, `siblings` **Lookup:** `search_nodes`, `get_concept` **Cross-references (wikilinks):** `references_from`, `references_to` **Semantic:** `suggest_gaps` **Write:** `create_concept`, `link_concepts`, `update_concept`, `merge_concepts`, `reindex` The vault is modeled as a tree: each concept and opaque-folder node has a single parent (its containing folder), all the way up to a `folder:` root. Wikilinks and tags are still parsed and stored, but they are *cross-references* — queryable via `references_from` / `references_to` rather than mixed into navigation. ## 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 ```jsonc { "vaultPath": ".", // vault root, relative to this config file "opaqueFolders": ["Projects/*"], // globs of folders that collapse to single nodes "exclude": ["Untitled*.md", "Templates"], // globs of paths to skip entirely (no node) "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.