![\"obsidian-forge\"](\"assets/obsidian-forge-logo.svg\"){kind=logo}
\n\n \n
\n ![\"npm](\"https://img.shields.io/npm/v/@blacksmithers/obsidian-forge-mcp.svg\")
\n ![\"license\"](\"https://img.shields.io/badge/license-MIT-blue.svg\"){kind=icon}
\n ![\"node](\"https://img.shields.io/badge/node-%3E%3D22-brightgreen.svg\"){kind=icon}
\n ![\"CI\"](\"https://github.com/blacksmithers/obsidian-forge-mcp/actions/workflows/ci.yml/badge.svg\"){kind=icon}
\n
\n 27 tools · Canvas with auto-layout · BM25 smart search · Vault intelligence
\n No Obsidian plugin required · Works on macOS, Linux, Windows\n
\n Canvas ·\n Search ·\n Intelligence ·\n All 27 Tools ·\n Quick Start\n
\n\n---\n\n## The Problem with Every Other Obsidian MCP\n\nI checked them all — mcp-obsidian, mcpvault, obsidian-mcp-server, obsidian-mcp-tools, obsidian-mcp-plugin. They read files. They write files. Some search. That's it.\n\nNone of them can create a visual diagram. None of them rank search results by relevance. None of them can tell an agent *\"here are the 12 themes in this vault and which files belong to which.\"*\n\nobsidian-forge does all three.\n\n| Feature | obsidian-forge | mcp-obsidian | mcpvault | obsidian-mcp-server |\n|---------|:-:|:-:|:-:|:-:|\n| Read / Write / Delete notes | ✅ | ✅ | ✅ | ✅ |\n| Full-text search | ✅ | ✅ | ✅ | ✅ |\n| Edit in-place | ✅ | ❌ | ✅ | ❌ |\n| Batch operations | ✅ | ❌ | ❌ | ❌ |\n| Daily notes | ✅ | ❌ | ❌ | ✅ |\n| Vault stats | ✅ | ❌ | ✅ | ❌ |\n| **Canvas — create with auto-layout** | ✅ | ❌ | ❌ | ❌ |\n| **Canvas — semantic read** | ✅ | ❌ | ❌ | ❌ |\n| **Canvas — patch (add/remove/update)** | ✅ | ❌ | ❌ | ❌ |\n| **Canvas — re-layout (dagre)** | ✅ | ❌ | ❌ | ❌ |\n| **BM25 smart search (Orama)** | ✅ | ❌ | ❌ | ❌ |\n| **Vault theme mapping (TF-IDF)** | ✅ | ❌ | ❌ | ❌ |\n| **Vault reorganization engine** | ✅ | ❌ | ❌ | ❌ |\n| **Regex find-and-replace (grep-sub)** | ✅ | ❌ | ❌ | ❌ |\n| **Batch rename / move with link updates** | ✅ | ❌ | ❌ | ❌ |\n| **Backlink analysis** | ✅ | ❌ | ❌ | ❌ |\n| **Frontmatter as structured data** | ✅ | ❌ | ❌ | ❌ |\n| **Directory management (delete, prune)** | ✅ | ❌ | ❌ | ❌ |\n| No Obsidian plugin required | ✅ | ❌ | ✅ | ❌ |\n\n---\n\n## Fewer Tokens. Same Intelligence.\n\nThe other Obsidian MCPs weren't designed for AI agents — they were designed for humans who happen to use AI. Every tool returns raw, verbose data that burns through context windows. obsidian-forge is **AI-infrastructure**: every response is shaped to minimize token consumption while maximizing semantic density.\n\n| Operation | Traditional MCP | obsidian-forge | Savings |\n|---|---|---|---|\n| Read a canvas | Raw JSON — coordinates, hex IDs, pixel dimensions | Semantic graph: labels + connections only | ~70-80% fewer tokens |\n| Search vault | Unranked grep dump — agent reads 50 results to find 3 | BM25-ranked top results with relevance scores | ~90% fewer tokens |\n| Understand vault structure | Agent reads files one by one (N calls × M tokens each) | One `vault_themes()` call returns clustered map | ~95% fewer tokens |\n\nTokens = API cost, context window space, and latency. Fewer tokens means faster, cheaper, smarter agents.\n\n---\n\n## Three Things No Other MCP Can Do\n\n### 🎨 Canvas Tools\n\n> The agent thinks in graphs. The tool thinks in pixels.\n\nAI agents create, read, modify, and re-layout [JSON Canvas](https://jsoncanvas.org/) files without touching a single coordinate. The agent describes a semantic graph. obsidian-forge calculates all geometry using [dagre](https://github.com/dagrejs/dagre) — the same Sugiyama layout engine behind Mermaid and React Flow.\n\n**canvas_create** — describe nodes and edges, get a fully laid-out `.canvas` file:\n\n```\nAgent sends: Obsidian renders:\n \n nodes: ┌───────────┐\n - API Gateway │ API │───┐\n - Auth Service │ Gateway │ │\n - Database └───────────┘ │\n - Cache ┌───────────┐ │ ┌───────────┐\n edges: │ Auth │───┼──▶│ Database │\n - API Gateway → Auth Service │ Service │ │ └───────────┘\n - API Gateway → Cache └───────────┘ │\n - Auth Service → Database │ ┌───────────┐\n - Cache → Database └──▶│ Cache │\n layout: { direction: \"LR\" } └───────────┘\n```\n\n**canvas_read** — semantic graph, not raw JSON:\n\n```\nInstead of: {\"id\":\"231bf38f\",\"x\":-635,\"y\":-420,\"width\":250,\"height\":70,...}\nAgent gets: { label: \"AXON\", connections: [\"Strategy\", \"AWS\", \"Resistance\"] }\n```\n\nA typical canvas with 15 nodes returns ~200 tokens as a semantic graph vs ~2,000+ tokens as raw JSON Canvas. The agent gets the same information at 10% of the cost.\n\n**canvas_patch** — modify with relative positioning:\n\n```\nadd_nodes: [{ label: \"New Module\", near: \"API Gateway\", position: \"below\" }]\nremove_nodes: [\"Deprecated Service\"] → cascade-removes all connected edges\n```\n\n**canvas_relayout** — fix a messy canvas with one call. Preview before committing.\n\n---\n\n### 🔍 Smart Search\n\n> Not grep. Elasticsearch-grade.\n\n[Orama](https://github.com/oramasearch/orama) BM25-ranked search with typo tolerance, stemming (26 languages), and field boosting. No ML, no API keys, no internet.\n\n```\nsmart_search(\"stripe webhook\")\n\n → Stripe-Webhooks.md score: 0.92\n \"...webhook endpoint configuration for handling Stripe events...\"\n \n → Refactor-Prompts.md score: 0.61\n \"...refactor the Stripe integration to use webhook signatures...\"\n\nvs search_content(\"stripe webhook\")\n → Returns EVERY file containing \"stripe\", unranked, no scoring\n```\n\nUnranked grep forces the agent to consume every result to find relevance. BM25 puts the answer at the top. Fewer results read = fewer tokens burned = faster, cheaper responses.\n\n**Field boosting:** title (3×) > tags (2.5×) > headings (2×) > content (1×).\n\n**Persistent index** at `.obsidian-forge/search-index.json` — survives restarts.\n\n---\n\n### 🧠 Vault Intelligence\n\n> Your vault has folders. Now it has a map.\n\nFiles land where the energy of the moment puts them. Themes bleed across folders — \"SpecForge\" ends up in `Projetos/`, `AI/prompts/`, `Content/`, and `Empresas/`. Nobody maintains a perfect taxonomy.\n\n**vault_themes** — scans every file, extracts distinctive terms via TF-IDF, clusters by similarity:\n\n```json\n{\n \"themes\": [\n {\n \"label\": \"SpecForge Frontend\",\n \"key_terms\": [\"impl\", \"dashboard\", \"widget\"],\n \"files\": 12,\n \"folders\": [\"32-AI/prompts/specforge\"],\n \"coherence\": 0.89\n },\n {\n \"label\": \"Content Strategy\",\n \"files\": 6,\n \"folders\": [\"80-Content\", \"70-Empresas\"],\n \"cross_folder\": true\n }\n ],\n \"orphans\": 5,\n \"cross_folder_warnings\": 3\n}\n```\n\nWithout this, an agent needs to `read_note` on every file individually to understand vault structure — hundreds of tool calls, thousands of tokens. One `vault_themes()` call replaces all of them.\n\n**vault_suggest** — actionable reorganization from the atlas:\n\n```json\n{\n \"suggestions\": [\n { \"type\": \"consolidate\", \"action\": \"Move Launch-Strategy.md → 80-Content/\" },\n { \"type\": \"create_moc\", \"action\": \"Create MOC-SpecForge-Frontend.md linking 12 files\" },\n { \"type\": \"archive\", \"action\": \"Move 8 stale files to 90-Archive/\" }\n ]\n}\n```\n\n**The full workflow:**\n\n```\n\"Organize my vault\"\n → vault_themes() maps 179 files into 15 themes\n → vault_suggest() generates 20 reorganization actions \n → human approves \"do it, skip the archive stuff\"\n → batch execution moves files, creates MOCs\n → canvas_create() visual theme map in Obsidian\n```\n\nThe vault maps itself.\n\n---\n\n## All Tools\n\n### Notes (6)\n| Tool | What it does |\n|------|-------------|\n| `read_note` | Read content + metadata. Fuzzy path resolution. |\n| `write_note` | Create or overwrite. |\n| `edit_note` | In-place find and replace. Exact match, must be unique. |\n| `edit_regex` | Regex find-and-replace. Single file or grep-sub across vault. Capture groups, dry run. |\n| `append_note` | Append to existing, or create if missing. |\n| `delete_note` | Move to `.trash` (safe) or permanent. Optional `cleanup_empty_parents` removes empty parent dirs. |\n\n### Search & Discovery (8)\n| Tool | What it does |\n|------|-------------|\n| `smart_search` | **BM25-ranked.** Typo tolerance, field boosting, snippets. |\n| `search_reindex` | Force re-index after bulk operations. |\n| `search_vault` | Fast filename/path search from in-memory index. |\n| `search_content` | Full-text grep. For exact/literal matches. |\n| `list_dir` | Directory listing with created/modified timestamps. Sort by name, date, or size. |\n| `recent_notes` | Recently modified files. Instant from index. |\n| `daily_note` | Today's daily note (or any date). |\n| `vault_status` | File counts, types, index health. |\n\n### Files (3)\n| Tool | What it does |\n|------|-------------|\n| `batch_rename` | Rename/move files. Explicit pairs or regex patterns. Auto-updates wikilinks. Dry run default. |\n| `delete_folder` | Delete empty or non-empty directories. Moves to `.trash` by default. Safety guards for `.obsidian`, `.git`, `.trash`. |\n| `prune_empty_dirs` | Find and remove all empty directories. Dry run default. Bottom-up pruning handles cascading empty dirs. |\n\n### Links (2)\n| Tool | What it does |\n|------|-------------|\n| `update_links` | Update all wikilinks across vault after moving/renaming a file. Dry run default. |\n| `backlinks` | Find all files that link to a given file. Line numbers, context, embed detection. |\n\n### Metadata (1)\n| Tool | What it does |\n|------|-------------|\n| `frontmatter` | Read/write/merge YAML frontmatter as structured data. No string parsing needed. |\n\n### Canvas (4)\n| Tool | What it does |\n|------|-------------|\n| `canvas_create` | Semantic graph → auto-laid-out `.canvas` via dagre. |\n| `canvas_read` | Canvas → semantic graph (labels + connections, not coordinates). |\n| `canvas_patch` | Add/remove/update with relative positioning + fuzzy matching. |\n| `canvas_relayout` | Re-layout existing canvas. Preview before committing. |\n\n### Intelligence (2)\n| Tool | What it does |\n|------|-------------|\n| `vault_themes` | TF-IDF theme extraction + clustering. Vault atlas with cross-folder warnings. |\n| `vault_suggest` | Reorganization engine: consolidate, create MOCs, archive stale, triage orphans. |\n\n### Batch (1)\n| Tool | What it does |\n|------|-------------|\n| `batch` | Execute multiple operations — read, write, edit, regex, rename, frontmatter, delete. Delete ops support `cleanup_empty_parents`. |\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) v22+\n- A folder with Markdown files (Obsidian vault or any structure)\n\n**Obsidian app is not required.** obsidian-forge operates directly on the filesystem. If Obsidian is open, it picks up changes in real time.\n\n### Install\n\n```bash\nnpm install -g @blacksmithers/obsidian-forge-mcp\n```\n\n### Configure\n\n**Claude Desktop** — edit `claude_desktop_config.json`:\n\n| OS | Config file location |\n|----|---------------------|\n| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |\n| Windows | `%APPDATA%\\Claude\\claude_desktop_config.json` |\n| Linux | `~/.config/Claude/claude_desktop_config.json` |\n\n> **Tip (Windows):** press `Win+R`, paste `%APPDATA%\\Claude`, hit Enter. The folder opens directly.\n\nmacOS / Linux:\n```json\n{\n \"mcpServers\": {\n \"obsidian-forge\": {\n \"command\": \"obsidian-forge\",\n \"args\": [\"/Users/you/Documents/MyVault\"]\n }\n }\n}\n```\n\nWindows:\n```json\n{\n \"mcpServers\": {\n \"obsidian-forge\": {\n \"command\": \"obsidian-forge\",\n \"args\": [\"C:\\\\Users\\\\you\\\\Documents\\\\MyVault\"]\n }\n }\n}\n```\n\n**Claude Code:**\n\n```bash\nclaude mcp add obsidian-forge -- obsidian-forge /path/to/your/vault\n```\n\n### Verify\n\nAsk your AI assistant: *\"List the files in my vault\"* — if it responds with your vault contents, you're connected.\n\n---\n\n## Under the Hood\n\n### Three Engines, One Index\n\n```\n@orama/orama (BM25 index — single source of truth)\n ├── smart_search query-driven \"find files about X\"\n ├── vault_themes corpus-driven \"what themes exist?\"\n └── vault_suggest action-driven \"how should I reorganize?\"\n\n@dagrejs/dagre (Sugiyama graph layout)\n ├── canvas_create semantic graph → positioned canvas\n ├── canvas_patch relative edits → absolute coordinates\n └── canvas_relayout messy canvas → optimized layout\n\nWikilink engine (zero dependencies)\n ├── update_links safe moves with automatic link repair\n ├── backlinks impact analysis before moves/deletes\n └── batch_rename rename + link update in one operation\n```\n\n### Dependencies\n\nTwo packages. Both MIT, TypeScript-native, zero sub-dependencies:\n\n| Package | Purpose | Size |\n|---------|---------|------|\n| [`@dagrejs/dagre`](https://github.com/dagrejs/dagre) | Sugiyama graph layout | ~15KB |\n| [`@orama/orama`](https://github.com/oramasearch/orama) | BM25 search engine | ~2KB core |\n\n### Architecture\n\n```\nsrc/\n├── tools/\n│ ├── notes/ read, write, edit, edit_regex, append, delete\n│ │ └── edit-regex.ts regex find-and-replace\n│ ├── files/ rename, move, directory management\n│ │ ├── batch-rename.ts rename/move with link updates\n│ │ ├── delete-folder.ts delete directories with safety guards\n│ │ └── prune-empty-dirs.ts find and remove empty directories\n│ ├── links/ wikilink management\n│ │ ├── link-utils.ts shared wikilink regex engine\n│ │ ├── update-links.ts fix links after moves\n│ │ └── backlinks.ts impact analysis\n│ ├── metadata/ frontmatter operations\n│ │ └── frontmatter.ts read/write/merge YAML frontmatter\n│ ├── search/ search_vault, search_content, list_dir, recent, daily, status\n│ │ ├── smart-search.ts BM25 search via Orama\n│ │ ├── search-reindex.ts full/incremental re-index\n│ │ ├── orama-engine.ts Orama wrapper + persistence\n│ │ └── markdown-parser.ts strip md, extract frontmatter/headings\n│ ├── intelligence/ vault analysis + reorganization\n│ │ ├── vault-themes.ts TF-IDF extraction + clustering\n│ │ └── vault-suggest.ts suggestions + batch execution\n│ ├── canvas/ JSON Canvas (jsoncanvas.org spec v1.0)\n│ │ ├── canvas-create.ts\n│ │ ├── canvas-read.ts\n│ │ ├── canvas-patch.ts\n│ │ ├── canvas-relayout.ts\n│ │ ├── layout-engine.ts dagre wrapper + edge side calc\n│ │ ├── canvas-utils.ts ID gen, text height, fuzzy match\n│ │ └── types.ts\n│ └── batch/ multi-operation execution\n```\n\n---\n\n## Roadmap\n\nWhat's coming next. Ordered by priority — community input shapes the sequence.\n\n### v0.6.0 — Vault Graph & Tags\n- **`vault_graph`** — Export the vault's link graph as a JSON adjacency list. Nodes = files, edges = wikilinks. Enables agents to reason about knowledge structure, find clusters, detect orphans, and identify bridge notes. Output compatible with D3, Cytoscape, or canvas_create for visual rendering.\n- **`tag_search`** — Search by YAML frontmatter tags, separate from content search. Filter by tag combinations (`tag:draft AND tag:specforge`). Returns files with matching tags plus their frontmatter metadata.\n- **`diff_note`** — Compare two notes (or two versions of the same note) and return a structured diff. Useful for agents reviewing changes, merging edits, or auditing vault history.\n\n### v0.7.0 — Template Engine & Smart Create\n- **`template_create`** — Create notes from templates with variable substitution (`{{date}}`, `{{title}}`, `{{tags}}`). Supports custom template folders. The agent describes intent, the tool handles boilerplate.\n- **`smart_create`** — AI-aware note creation. Analyzes vault themes and suggests optimal location, tags, and links for new notes. \"Write about X\" → creates the note in the right folder with relevant backlinks.\n\n### v0.8.0 — Performance at Scale\n- Large vault optimization (10k+ files) — incremental indexing, lazy loading, memory-mapped file access\n- Parallel batch operations where order independence allows\n- Index compression for faster startup on large vaults\n- Benchmark suite with reproducible performance targets\n\n### v1.0.0 — Stability & Ecosystem\n- Comprehensive test suite with >90% coverage\n- Stable API — no breaking changes without major version bump\n- Plugin ecosystem hooks — allow community extensions\n- Published to MCP registry\n- Obsidian community plugin (optional companion for enhanced integration)\n\n### Community-Driven\nOpen an issue tagged `roadmap` to propose features. The most-requested items move up the queue. This is an open forge — the community shapes the steel.\n\n---\n\n## The Forge is Open\n\nobsidian-forge is the first open-source tool from the **Blacksmithers** — a community of builders who forge tools that build things.\n\nWe don't wrap APIs and call it innovation. We build real engines — BM25 search, graph layout, TF-IDF clustering — because the tools AI agents use should be as rigorous as the agents themselves.\n\n**If that resonates, you're already one of us.**\n\n### Contributing\n\nOpen an issue first to discuss changes. PRs welcome — especially for:\n\n- Semantic similarity search (embedding-based, complementing BM25)\n- Canvas layout algorithms beyond Sugiyama (force-directed, circular)\n- Performance improvements for large vaults (10k+ files)\n- Windows-specific edge cases and path handling\n- New language stemmers for smart search\n\n### Community\n\n- 🔨 [blacksmithers.dev](https://blacksmithers.dev) — The movement\n- 🐦 [@gabgforge](https://x.com/gabgforge) — Engineer · Founder · Blacksmither\n- 💬 [GitHub Discussions](https://github.com/orgs/blacksmithers/discussions) — Ideas, feedback, show & tell\n\n### License\n\n[MIT](LICENSE) — [Solutions Forge LTDA](https://solutionsforge.tech)\n\n---\n\n\n Stop automating spreadsheets. Start forging.\n
\n","readmeFilename":"README.md"}