Obsidian Remote MCP Server

Obsidian remote MCP server

Reach your Obsidian vault from anywhere, in Claude.ai and Claude Code, without Obsidian running and without the vault on the machine you are working from. A vault server that reads and writes the files directly - notes, properties, tags, links, canvases and attachments - behind an OAuth 2.1 authorization server, so it can be added as a Claude.ai custom connector while static bearer tokens keep working for Claude Code.

Requirements

• An always-on Linux machine, such as a home server, a NAS or a VPS

• Your vault synced to it with Obsidian Sync via Headless Sync, Syncthing, Obsidian Git or Nextcloud

• Node.js 18 or newer

• An HTTPS reverse proxy or tunnel

Related MCP server: Obsidian MCP Server

Features

• Read and write your vault from Claude.ai and Claude Code

• 36 tools covering notes, headings, properties, tags, links, folders, search, canvases, daily notes and attachments

• Full Obsidian canvas support: create, read and edit .canvas files, with automatic layout

• Moves and renames rewrite the links that pointed at the note, wikilink and markdown alike

• OAuth 2.1 with PKCE, dynamic client registration, and refresh token rotation

• Static bearer token accepted alongside OAuth, so both clients work at once

• Works with Obsidian closed - the vault is read from disk, no plugins needed

• Serves multiple vaults from one endpoint

• No inbound firewall port needed when paired with a Cloudflare Tunnel

How it works

vault-mcp.js (stdio)       reads and writes the vault
  -> supergateway          stdio to Streamable HTTP, :8420
  -> auth-server.js        OAuth 2.1 + token check, :8422
  -> nginx                 :8421
  -> Cloudflare Tunnel     https://obsidian-mcp.example.com

Only the auth server is reachable from outside. Port 8420 speaks no authentication at all. supergateway offers no flag to choose a bind address and listens on every interface, so the unit confines it with IPAddressDeny=any and IPAddressAllow=localhost; without that it would answer anyone on the LAN.

Claude.ai custom connectors accept OAuth or, in a beta not everyone has, a fixed request header. Claude Code accepts a header directly. This serves both: an OAuth 2.1 flow per the MCP 2025-06-18 authorization spec, and a static token read from a file.

Install

Run this on the machine that holds the vault. It asks for your vault path and hostname, installs the code, generates a password and a token, and writes the service files ready to start.

curl -fsSL https://raw.githubusercontent.com/rollecode/obsidian-remote-mcp/main/install.sh | bash

Install with Claude Code

Claude Code can do the whole thing, including the tunnel and the reverse proxy, which the installer deliberately leaves alone because every setup differs. Start it in an empty directory:

claude

Then give it this:

Install https://github.com/rollecode/obsidian-remote-mcp on this machine.

Read the repository's README for the architecture and the manual setup steps, then work out what applies here rather than assuming. Specifically:

1. Find my Obsidian vault and confirm the path with me before using it.
2. Install the code and dependencies, set a login password, and generate a static token for Claude Code.
3. Install and start both systemd services with the real paths for this machine.
4. Expose it over HTTPS on a hostname I give you. Check what I already run - Cloudflare Tunnel, nginx, Caddy, Traefik - and use that rather than installing something new. Never open a router port without asking me first.
5. Verify it end to end: the discovery endpoints return valid JSON, an unauthenticated request gets 401 with a WWW-Authenticate header, and the static token gets a 200 from the MCP endpoint.
6. Print the Claude.ai connector URL and the exact claude mcp add command for Claude Code, and tell me the password.

This exposes read and write access to my notes over the internet, so tell me anything that weakens that before you do it.

Manual setup

Install first:

git clone https://github.com/rollecode/obsidian-remote-mcp.git
cd obsidian-remote-mcp
npm install

Then set a password. This is what you type on the OAuth login page, and only its scrypt hash is stored.

node set-password.js 'your-password-here'

Generate a static token if you want to use Claude Code, which can send a header directly and skip the login page.

mkdir -p ~/.config/obsidian-mcp
openssl rand -hex 32 > ~/.config/obsidian-mcp/token
chmod 600 ~/.config/obsidian-mcp/token

Install the services, replacing YOUR_USER, the vault path and ISSUER in the unit files with your own.

sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now obsidian-mcp obsidian-mcp-auth

Expose it. Add the nginx site from nginx/obsidian-mcp.conf, then point a Cloudflare Tunnel at http://localhost:8421. Any HTTPS reverse proxy works, but a tunnel avoids opening a router port.

ingress:
  - hostname: obsidian-mcp.example.com
    service: http://localhost:8421

cloudflared tunnel route dns YOUR_TUNNEL obsidian-mcp.example.com
sudo systemctl restart cloudflared

Finally, connect. In Claude.ai go to Customize → Connectors → Add custom connector, enter https://obsidian-mcp.example.com/mcp and leave Client ID and Client Secret blank, since the server registers Claude automatically. You will be asked for the password you set earlier. Remember to enable the connector in each conversation from the + menu.

For Claude Code, use the static token.

claude mcp add --transport http obsidian https://obsidian-mcp.example.com/mcp \
  --header "Authorization: Bearer $(cat ~/.config/obsidian-mcp/token)"

Tools

Every tool takes an optional vault. With one vault it is inferred, and with DEFAULT_VAULT set the auth server fills it in, so it rarely needs passing. Anything addressing a file takes path relative to the vault root; note tools also accept the older filename plus folder pair.

Notes

Canvas

Tags, links and structure

Browsing and search

Daily notes and attachments

Canvas support

Obsidian canvases are JSON Canvas files, not markdown, which is why a markdown-only server cannot touch them. Coordinates are the part a language model handles worst, so x/y/width/height are optional everywhere and filled from a grid; edit-canvas also has a layout operation that re-flows an existing canvas into a grid, column or row.

Node ids are yours to choose, so edges can reference nodes in the same call:

{
  "path": "Maps/Flow.canvas",
  "nodes": [
    { "id": "start", "type": "text", "text": "# Kickoff" },
    { "id": "spec", "type": "file", "file": "Projects/Spec.md" }
  ],
  "edges": [{ "from": "start", "to": "spec", "label": "leads to" }]
}

fromNotes builds a canvas straight from a set of notes, and with linkEdges it draws an arrow wherever one of them links to another, turning a corner of the vault graph into a canvas in one call.

Obsidian writes fields the spec does not define, styleAttributes on every node and a top-level metadata object, and it discards a canvas it cannot parse. Every edit preserves what it does not recognise, and a failed operation writes nothing at all.

Development

The vault server runs on its own, without the auth server or supergateway, which is the quickest way to try a change:

npm install
node vault-mcp.js ~/Documents/YourVault
npx @modelcontextprotocol/inspector node vault-mcp.js ~/Documents/YourVault

npm test builds a throwaway vault, starts the server over stdio and drives every tool through a real MCP client, checking the files on disk afterwards. It touches nothing outside its own temp directory.

Endpoints

Configuration

The vault server

vault-mcp.js speaks MCP over stdio and touches nothing but the vault directory. It replaced obsidian-mcp in 1.5.0, which had to be patched on install to stop it going deaf after 60 seconds idle and to make edit-note advertise its parameters at all, and which was never going to grow canvas support.

Listings, tags, links and search all read one in-memory index. It stats the tree on demand and re-parses only the files whose size or mtime moved, so a vault of 6500 notes costs a few seconds on the first call and single-digit milliseconds after that. Every write invalidates it, so a tool never reads its own change back as stale.

Three things are refused outright rather than left to care:

• A path that resolves outside the vault, including through a symlink planted inside it

• Any write into .obsidian, where a bad value corrupts the vault for every client that syncs it

• A canvas edit where any operation fails, which writes nothing rather than half of a list

Deletions move to the vault's .trash, where Obsidian lists them under deleted files, unless permanent is set. Writes go to a hidden temp file and are renamed into place, so a sync client never reads a half-written note.

Two guards in the auth server keep a stuck child from hanging a client:

• A call that goes CALL_TIMEOUT_MS without a byte from upstream is cut, and the session is terminated so the wedged child dies with it. The SSE GET stream is exempt, since it is idle by design.

• A request carrying a session the upstream no longer knows gets 404, not the 400 supergateway returns. Only 404 obliges a client to send a fresh InitializeRequest, per the session management rules in the MCP 2025-06-18 transport spec, so clients recover on their own.

Security

• Authorization codes are single use and expire in 60 seconds

• PKCE is required and only S256 is accepted

• Redirect URIs are matched exactly against registered values

• Refresh tokens rotate on every use

• Tokens are stored as SHA-256 hashes, so the database holds no usable credentials

• Tokens are bound to the resource they were issued for and rejected elsewhere

• The password is stored as a scrypt hash, compared in constant time

This grants write access to your vault over the internet. Use a strong password, keep ISSUER on HTTPS, and remember that anyone holding the static token has the same access without the login page.