Obsidian MCP
Interact with your Obsidian vault using the Model Context Protocol, enabling AI assistants to read, write, and manipulate notes.Read full description
takuya0206LABSCO SUMMARY
Two tools, and the vault stays on your disk.
Most vault servers register one tool per operation, and the whole schema block is on the wire before the agent has done anything; Nexus registers two and hands out the rest on request, which is why it works with a small local model as well as with Claude. The trade is a contract you have to respect — every call needs memory and goal, and calls without them are rejected outright, so brief the agent before you point it at your notes.
What it is
An Obsidian plugin that puts your vault behind MCP. Nexus is the successor to Claudesidian, and legacy installs in .obsidian/plugins/claudesidian-mcp/ still work. It exposes exactly two tools to MCP clients — toolManager_getTools for discovery and toolManager_useTools for execution — so a client loads schemas for the agents it actually needs instead of the whole catalogue up front. Every useTools call carries workspaceId, sessionId, memory and goal at the top level, which is what keeps a long task coherent across calls. Notes stay in the vault.
What you get
- Two tools instead of a catalogue:
toolManager_getToolsreturns schemas for what you name —"--help"for the agent list,"storage"for one agent,"storage list"for a single tool's full argument schema — andtoolManager_useToolsruns them - Vault file work through the
storageandcontentagents:storage list,storage move,content read,content write. Several commands batch into oneuseToolscall, separated by a top-level comma; commas inside a quoted value stay literal - Workspace memory and project state that survive a session ending —
memory load-workspaceandmemory create-statecarry the active task, active files and next steps - Web pages saved into the vault as Markdown with
web capture-markdown, one of the few features that also works on mobile - Native chat inside Obsidian on desktop and mobile, with live voice, read-aloud and audio and video generation, using provider keys you supply
- A shell path with no MCP config at all: the
nexuscommand talks to the same local socketconnector.jsuses —nexus toolsto discover,nexus useto run one,nexus vaultsandnexus doctorwhen something is off.--memoryand--goalare required on everyuse - Transport flags for text that shells mangle: any value-taking flag has a
--<flag>-stdinand--<flag>-fileform, so Markdown, YAML frontmatter and wikilinks arrive intact - Desktop-only extras that skip loading on mobile instead of erroring: semantic search, adaptive search, PDF and audio ingestion, and Python analysis over the vault's CSV and Excel files
Requirements
Obsidian with the Nexus plugin enabled, and Node.js v18 or newer for anything outside Obsidian. Install manifest.json, styles.css and main.js into .obsidian/plugins/nexus/. connector.js does not ship with the community release — generate it from Nexus settings → Get started → External agents, then point the client at node /path/to/Vault/.obsidian/plugins/nexus/connector.js. Obsidian has to be open for that vault, because the bridge connects to the live process over a unix socket on macOS and Linux or a named pipe on Windows. MCP clients, the local CLI and semantic search are desktop-only. The plugin makes no network calls on its own: provider APIs are contacted only after you enter that provider's key and use it, and there is no telemetry.
Setup effort
Follow the published steps
USE CASES
01
Working through your notes from Claude Desktop
Ask for the agent catalogue, pull the schema for just the agent you need, then run the command — reading, writing and moving files inside the vault without leaving the conversation.
02
Driving your vault from a coding agent's shell
Install the nexus command and Claude Code, Cursor or Codex can read and write notes with no MCP config at all — the CLI is a thin client over the same socket.
03
Picking up a long project where you left it
Load the workspace and the saved state, and the agent starts with the active task, the files in play and the next steps instead of an empty context.
04
Filing a web page you want to keep
Capture the page as Markdown straight into the vault, so the reference lives beside the notes that cite it rather than in a browser tab.
05
Writing a long note without shell quoting eating it
Pipe the body in with a -stdin transport flag or pass a local path with -file; the destination stays vault-relative and the text arrives unflattened.
BEFORE YOU INSTALL
What to know first
Requires
- Obsidian 1.10+ with the Nexus plugin enabled
- Node.js v18+
- Obsidian open on that vault while your client is connected
Where it runs
All 8 documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
Download manifest.json, styles.css and main.js from the latest release at https://github.com/ProfSynapse/claudesidian-mcp/releases
Put them in .obsidian/plugins/nexus/ inside your vault and enable Nexus in Obsidian
In Nexus settings → Get started → External agents, create connector.js (it is generated locally and does not ship in the release)
In the configuration for your client below, <YOUR_PATH_TO_VAULT> is the full path to your vault; keep Obsidian open on that vault while the client uses it
MCP Clients
Claude Desktop, Gemini CLI, Cursor, Windsurf
JSON
{
"mcpServers": {
"nexus": {
"command": "node",
"args": [
"<YOUR_PATH_TO_VAULT>/.obsidian/plugins/nexus/connector.js"
]
}
}
}Claude Code
CLAUDE CODE · TERMINAL
claude mcp add nexus -- node <YOUR_PATH_TO_VAULT>/.obsidian/plugins/nexus/connector.jsCodex
CODEX · TERMINAL
codex mcp add nexus -- node <YOUR_PATH_TO_VAULT>/.obsidian/plugins/nexus/connector.jsVS Code
VS CODE · JSON
{
"servers": {
"nexus": {
"type": "stdio",
"command": "node",
"args": [
"<YOUR_PATH_TO_VAULT>/.obsidian/plugins/nexus/connector.js"
]
}
}
}Cline
CLINE · JSON
{
"mcpServers": {
"nexus": {
"command": "node",
"args": [
"<YOUR_PATH_TO_VAULT>/.obsidian/plugins/nexus/connector.js"
],
"disabled": false,
"alwaysAllow": []
}
}
}
