obsidian-mcp

Remote MCP server that gives AI agents read/write access to your Obsidian vaults. On personal machines it mounts the real local vault folders used by the Obsidian app; on server-style machines without local desktop vaults it falls back to syncing with obsidian-headless.

Installation

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

That installs the app, runs interactive setup, and prints a remote MCP config. On personal machines it uses your real desktop vaults directly and lets you choose either a temporary Cloudflare URL or a persistent Cloudflare Tunnel hostname.

Which Mode Should I Use?

• Laptop or desktop with the Obsidian app already installed: use local.
• VPS, home server, or separate always-on machine: use production.
• If local desktop vaults are detected, obsidian-headless is blocked on that machine to avoid sync conflicts.

Modes

Mode	Best for	Remote URL	URL stability	Infra burden	Survives reboot by default
Local	Running on your own machine with the Obsidian app	Yes	Temporary or stable, depending on tunnel choice	Medium	No
Production	Long-term self-hosting	Yes	Stable domain	Higher	Yes

1. Local

• Uses local desktop vaults directly.
• Lets you choose a temporary trycloudflare.com URL or a persistent Cloudflare Tunnel hostname.
• Persistent local mode requires a Cloudflare-managed domain.
• Best for running on your own machine without obsidian-headless.

Manage local-mode processes:

npm run setup
npm run status
npm run logs
npm run stop

2. Production

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

• Uses obsidian-headless, Caddy, and system services.
• Refuses to run on machines with local desktop vaults.
• Best for a stable endpoint on a separate always-on machine.
• If you use your own domain, point its A record or AAAA record at the server's public IP.
• If you use sslip.io, no DNS changes are needed. The setup flow prefers an IPv4-based hostname when available because it is more widely reachable from clients.

Prerequisites

• a machine that can stay online while you use the MCP server
• for server or headless mode: an Obsidian Sync subscription and a machine without local Obsidian desktop vaults
• for local mode on your own machine: the Obsidian app installed with at least one local vault configured
• for persistent local mode: a Cloudflare-managed domain

Where Files Live

• Install directory:
  • user install default: ~/.local/share/obsidian-mcp
  • production install default: /opt/obsidian-mcp
• Local generated config for this install: .env
• Local runtime state for this install: .obsidian-mcp/
  • PID files
  • logs
  • active mode marker
  • mounted desktop-vault map
• Headless sync mirrors: vaults/
  • only used when the machine is running obsidian-headless
• Real desktop vault folders:
  • not copied into this repo
  • not owned by this app
  • mounted directly from the paths already managed by the Obsidian app
• ~/.obsidian-headless
  • owned by obsidian-headless
  • stores its auth/local sync state
  • not removed by npm run uninstall
• Cloudflare Tunnel resources for local mode
  • named tunnel and DNS route live in your Cloudflare account
  • not removed by npm run uninstall

Manual Setup

If you want to install things yourself instead of using install.sh:

1. Clone and enter the repo:

git clone https://github.com/hanzpo/obsidian-mcp.git
cd obsidian-mcp

2. Install dependencies:

Local mode also needs:

brew install cloudflared              # macOS
# or install cloudflared another way on Linux

Headless/server mode also needs:

npm install -g obsidian-headless

Production also needs:

# install Caddy

3. Run setup:

npm run setup

Client Config

Both modes print a ready-to-paste MCP config at the end. It looks like this:

{
  "mcpServers": {
    "obsidian": {
      "type": "streamableHttp",
      "url": "https://your-endpoint.example/mcp",
      "headers": {
        "Authorization": "Bearer <your-api-key>"
      }
    }
  }
}

Tools

Tool	Description
read_note	Read a note's content and metadata
read_notes	Batch read up to 10 notes
create_note	Create a note with optional frontmatter
edit_note	Append, prepend, or find-and-replace
delete_note	Delete a note (requires confirmation)
move_note	Move or rename a note
list_directory	Browse vault structure
search_notes	Full-text search with BM25 ranking
get_frontmatter	Read YAML frontmatter as JSON
update_frontmatter	Merge or remove frontmatter fields
manage_tags	Add, remove, or list tags
get_vault_stats	Vault statistics and recent files
get_links	Outgoing wikilinks and backlinks

Path model:

• In single-vault mode, tool paths are relative to that vault root.
• In mounted desktop mode, list_directory with an empty path shows the top-level vault aliases first, and other tool paths should be prefixed with one of those aliases such as work/... or personal/....

Commands

Start with:

npm run help

Recommended commands:

Command	What it does
npm run setup	Interactive setup. Choose local or production
npm run status	Show status for the active mode
npm run logs	Tail logs for the active mode
npm run stop	Stop the active mode
npm run restart	Restart the active mode
npm run update	Refresh repo files and rerun setup for the active mode
npm run build	Compile TypeScript
npm run check	Type-check, lint, and test
npm run keygen	Generate or rotate the API key
npm run uninstall	Safely remove obsidian-mcp setup from this machine

Active Mode

• npm run setup is the only setup entrypoint.
• During setup, you choose local or production.
• That choice is remembered in .obsidian-mcp/mode.
• After that, npm run status, logs, stop, restart, and update act on the active mode automatically.
• If no active mode is detected, those commands tell you to run npm run setup first.

Auth Notes

• The printed client config uses Authorization: Bearer <api-key>, which is the preferred option.
• For compatibility with some clients and transports, the server also accepts X-API-Key, ?api_key=..., and ?token=....
• Temporary local mode uses trycloudflare.com, so the URL can change on restart.
• Persistent local mode uses a named Cloudflare Tunnel hostname, so the URL stays the same, but the machine and tunnel still need to be running.

Troubleshooting

Local tunnel did not come up

npm run logs

Look at .obsidian-mcp/logs/cloudflared.log.

Sync is not working

ob sync-list-remote
npm run logs

If ob login keeps asking for credentials, run it again and rerun setup.

Production HTTPS/certificate errors

If using sslip.io, make sure ports 80 and 443 are open. Caddy needs port 80 for the ACME challenge.

ufw allow 80/tcp
ufw allow 443/tcp

Re-running setup

setup.sh is safe to re-run. In local mode it restarts the background MCP and tunnel processes. In production it refreshes services and configuration.

What npm run update does

• refreshes the repo files
• uses git pull for git checkouts
• falls back to downloading the latest repo archive for installer-style checkouts
• reruns setup for the active mode
• local stays local, production stays production

Start over safely

npm run uninstall

That removes obsidian-mcp's generated config and services from this machine after an explicit confirmation prompt, but intentionally preserves:

• your real Obsidian desktop vault folders
• synced vault contents under vaults/
• ~/.obsidian-headless
• Cloudflare Tunnel resources such as named tunnels and DNS routes
• remote Obsidian Sync state

Uninstall vs Purge

• npm run uninstall is a safe uninstall.
• It removes this app's generated config, runtime files, and installed services from this machine.
• It does not delete your notes, your desktop vault folders, your headless state, your Cloudflare Tunnel resources, or your remote Obsidian Sync state.
• If you want a real purge of synced mirrors, ~/.obsidian-headless, or Cloudflare tunnel resources, do that manually after uninstall.

Recovery

• If something looks broken, start with npm run status and npm run logs.
• If you changed configuration or updated the repo, run npm run update.
• If you want to choose the mode again or rebuild local state, rerun npm run setup.
• If you want to remove the app cleanly without touching note state, run npm run uninstall.

Development

npm ci
npm run dev
npm test
npm run check