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

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:

{
  "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

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:

.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.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

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.