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.
• Inline AI Editing – Select text, right-click or use hotkey, and transform it with AI instructions.
• 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	✅	✅
Inline AI Editing	✅	✅ (command palette only)
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

---

Inline AI Editing

Edit selected text directly in your notes using AI:

1. Select text in any note
2. Trigger via:
   • Right-click → Edit with AI (requires "Native menus" disabled in Obsidian settings)
   • Command palette → Edit selection with AI
3. Enter instruction (e.g., "Make this more concise", "Translate to French")
4. Generate – Watch streaming preview with cancel option
5. Review & Apply – Edit the result, retry, or apply to replace original text

Feature	Description
Model Selection	Dropdown to choose from configured providers
Streaming Preview	See AI output as it generates
Cancel Support	Stop generation mid-stream
Editable Result	Modify AI output before applying
Retry	Regenerate with same or new instruction
Undo	Standard Ctrl/Cmd+Z after applying

---

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.