Nexus MCP for Obsidian

Nexus turns your Obsidian vault into an MCP-enabled workspace. It exposes safe, structured tools that AI copilots can call to read/write notes, manage folders, run searches, and maintain long-term memory—all while keeping data local to your vault.

Nexus is the successor to Claudesidian. Legacy installs in .obsidian/plugins/claudesidian-mcp/ still work.

Highlights

• Two-Tool Architecture – Just 2 MCP tools (getTools + useTools) replace 40+ individual tools, reducing upfront token cost by ~95%.

• Native Chat View – Stream tool calls, branch conversations, and manage models directly inside Obsidian.

• Workspace Memory – Workspaces, states, and traces in .nexus/ (sync-friendly JSONL + local SQLite cache).

• Local Semantic Search – Desktop-only embeddings via sqlite-vec vector search—no external API calls.

• Full Vault Operations – Create, read, update, delete notes, folders, frontmatter, and batch edits.

• Multi-Provider Support – Anthropic, OpenAI, Google, Groq, Mistral, OpenRouter, Perplexity, Requesty, plus local servers (Ollama, LM Studio).

• Multi-Vault Ready – Independent MCP instances per vault.

Platform Notes

Two-Tool Architecture

Nexus exposes exactly 2 tools to MCP clients like Claude Desktop:

Why This Matters

• ~95% token reduction in upfront schemas (~15,000 → ~500 tokens)

• Works great with small context window models (local LLMs)

• Context-first design captures memory/goal for every operation

Context Schema

Every useTools call includes context that helps maintain continuity:

Available Agents & Tools (34 total)

Install

1. Download the latest release assets: manifest.json, styles.css, main.js, connector.js

2. Place them in .obsidian/plugins/nexus/ (or keep legacy .obsidian/plugins/claudesidian-mcp/)

3. Enable Nexus in Obsidian Settings → Community Plugins

4. Restart Obsidian after first install

Configure Claude Desktop

Add the Nexus server to your claude_desktop_config.json:

Or use the one-click setup: Settings → Nexus → Get Started → MCP Integration → Add Nexus to Claude

After adding, fully quit and relaunch Claude Desktop.

Using Native Chat

1. Configure a provider in Settings → Nexus → Providers

2. Open chat via ribbon icon or command palette (Nexus: Open Nexus Chat)

3. Type / for tools, @ for custom agents, [[ to link notes

4. Tool calls stream live with collapsible result panels

Workspace Memory

All data lives in .nexus/ inside your vault:

• Each tool call is tagged to a workspace automatically via context

• Create/load workspaces and save immutable state snapshots via tools or chat UI

• Archive workspaces and states for cold storage (restorable)

• No external database required

Semantic Search

Use searchManager.searchContent with semantic: true for meaning-based search:

• Desktop only – Embeddings run locally via iframe-sandboxed transformers.js

• Model: Xenova/all-MiniLM-L6-v2 (384 dimensions, ~23MB, cached in browser IndexedDB)

• Vectors: Stored in .nexus/cache.db via sqlite-vec for fast similarity search

• First run downloads the model (requires internet); subsequent runs are fully offline

• Watch the status bar for indexing progress; click to pause/resume

Multi-Vault Setup

• Each vault runs its own MCP server with key nexus-[vault-name]

• Add one entry per vault in your MCP client config

• Keep vaults open to keep their servers reachable

Security & Privacy

• MCP server binds locally only—no remote listeners

• All file operations stay inside the active vault

• Network calls only for remote LLM providers (per your API keys)

• Embeddings download once, then run fully on-device

Troubleshooting

Development

See CLAUDE.md for architecture details and contribution notes.

License

MIT License - see LICENSE for details.

Questions or issues? Open a GitHub issue with your OS, Obsidian version, and any console logs.