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
| Feature | Desktop | Mobile |
|---|---|---|
| Native Chat | ✅ | ✅ |
| MCP Bridge (Claude Desktop) | ✅ | — |
| Local Providers (Ollama/LM Studio) | ✅ | — |
| Semantic Embeddings | ✅ | — |
| Cloud Providers | ✅ | ✅ (fetch-based only) |
Two-Tool Architecture
Nexus exposes exactly 2 tools to MCP clients like Claude Desktop:
| Tool | Purpose |
|---|---|
toolManager_getTools | Discovery – Returns schemas for requested agents/tools |
toolManager_useTools | Execution – Runs tools with unified context |
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:
{
workspaceId: string; // Scope identifier (name or UUID)
sessionId: string; // Session name (system assigns standard ID)
memory: string; // Conversation essence (1-3 sentences)
goal: string; // Current objective (1-3 sentences)
constraints?: string; // Rules/limits (1-3 sentences, optional)
}
Available Agents & Tools (34 total)
| Agent | Purpose | Tools |
|---|---|---|
| contentManager | Note reading/editing | read, write, update |
| storageManager | File/folder management | list, createFolder, move, copy, archive, open |
| searchManager | Search operations | searchContent, searchDirectory, searchMemory |
| memoryManager | Workspace/state management | createWorkspace, listWorkspaces, loadWorkspace, updateWorkspace, archiveWorkspace, createState, listStates, loadState |
| promptManager | Custom prompts & LLM | listModels, executePrompts, listPrompts, getPrompt, createPrompt, updatePrompt, archivePrompt, generateImage, subagent |
| canvasManager | Canvas operations | read, write, update, list |
Install
- Download the latest release assets:
manifest.json,styles.css,main.js,connector.js - Place them in
.obsidian/plugins/nexus/(or keep legacy.obsidian/plugins/claudesidian-mcp/) - Enable Nexus in Obsidian Settings → Community Plugins
- Restart Obsidian after first install
Configure Claude Desktop
Add the Nexus server to your claude_desktop_config.json:
{
"mcpServers": {
"nexus-your-vault": {
"command": "node",
"args": [
"/path/to/Vault/.obsidian/plugins/nexus/connector.js"
]
}
}
}
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
- Configure a provider in Settings → Nexus → Providers
- Open chat via ribbon icon or command palette (Nexus: Open Nexus Chat)
- Type
/for tools,@for custom agents,[[to link notes - Tool calls stream live with collapsible result panels
Workspace Memory
All data lives in .nexus/ inside your vault:
.nexus/
├── conversations/*.jsonl # Chat history (syncs across devices)
├── workspaces/*.jsonl # Workspace events
└── cache.db # SQLite cache (auto-rebuilt, not synced)
- 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.dbvia 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
| Issue | Solution |
|---|---|
| Server not found | Settings → Nexus → Get Started → MCP Integration → Add Nexus to Claude, then restart Claude Desktop |
| Pipes not created | Ensure Obsidian is open; Windows uses nexus_mcp_<vault> named pipes |
| WebLLM crashes | Currently disabled due to WebGPU bug on Apple Silicon; use Ollama or LM Studio |
| Legacy install | Paths to .obsidian/plugins/claudesidian-mcp/connector.js still work |
Development
npm install # Install dependencies
npm run dev # Development build with watch
npm run build # Production build
npm run test # Run tests
npm run lint # Run ESLint
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.