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. Wraps obsidian-mcp in an OAuth 2.1 authorization server so it can be added as a Claude.ai custom connector, and keeps static bearer tokens 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

Features

• Read and write your vault from Claude.ai and Claude Code
• 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

obsidian-mcp (stdio)
  -> 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 and stays bound to localhost.

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

Provided by obsidian-mcp.

Tool	Description
read-note	Read a note
create-note	Create a note
edit-note	Edit a note
delete-note	Delete a note, to trash unless permanent
move-note	Move or rename a note
search-vault	Full text search
create-directory	Create a folder
add-tags	Add tags to a note
remove-tags	Remove tags from a note
rename-tag	Rename a tag across the vault
list-available-vaults	List configured vaults

Most tools take {vault, folder, filename}. delete-note takes {vault, path} instead.

Endpoints

Path	Purpose
/mcp	The MCP endpoint, requires a token
/.well-known/oauth-protected-resource	RFC 9728 resource metadata
/.well-known/oauth-authorization-server	RFC 8414 server metadata
/register	RFC 7591 dynamic client registration
/authorize	Login page and authorization code issuance
/token	Token exchange and refresh
/healthz	Health check

Configuration

Variable	Default	Purpose
ISSUER	required	Public HTTPS base URL, no trailing slash
PORT	8422	Port the auth server listens on
UPSTREAM	http://127.0.0.1:8420	Where supergateway is listening
CONFIG_DIR	~/.config/obsidian-mcp	Password hash, static token, OAuth database
DEFAULT_VAULT	unset	Vault used when a tool call omits one. Serving more than one vault without this makes Claude ask which to use on every call

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.