obsidian-remote-mcp

Read and edit your Obsidian notes from Claude, ChatGPT, and other MCP clients, even when you're away from your computer.

Run this self-hosted server on a NAS, a cloud server, or an always-on computer with a local copy of your vault. AI apps connect over HTTPS with browser sign-in or an API key. The core tools work directly with your Markdown files, so Obsidian doesn't need to be running.

Features

• Ask AI to find notes, add to a journal, or update one section of a project note. Tools also support frontmatter and batches of notes.

• Use your existing daily, weekly, and other periodic note settings. Moving or renaming notes updates the wikilinks pointing to them.

• Give agents your vault's instructions and a folder map with vault_context. It reads AGENTS.md, CLAUDE.md, or a guidance file you choose.

• Optional add-ons: Obsidian app commands, semantic search, URL clipping, and note skimming. See Optional features.

• Choose editing and Obsidian app permissions separately for each connection approved through browser sign-in. Use .mcpignore to exclude private folders from file tools.

• Atomic writes keep Obsidian and sync services from reading partially written notes. Optional version checks reject updates based on an outdated copy.

Related MCP server: Another bloated Obsidian MCP Server

How it fits together

┌─ sync ─────────────┐
│ ex. Obsidian Sync, │
│ git, rsync         │
└────────────────────┘
           │
           ▼
┌┄┄┄┄┄┄┄┄┄┄┬┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┐
┆ your machine — VPS, NAS, always-on PC/Mac    ┆
┆                                              ┆
┆    ┌─ vault ──┐      ┌─ server ────────────┐ ┆
┆    │ your .md │◄────►│ obsidian-remote-mcp │ ┆
┆    │ files    │      │ (this repo)         │ ┆
┆    └──────────┘      └─────────────────────┘ ┆
┆                                 │            ┆
└┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┼┄┄┄┄┄┄┄┄┄┄┄┄┘
                                  │
                                  ▼  over HTTPS
                     ┌─ access ───────────────┐
                     │ ex. Cloudflare Tunnel, │
                     │ Tailscale              │
                     └────────────────────────┘
                                  │
                                  ▼  authenticated MCP connection
                      ┌─ client ─────────────┐
                      │ ex. Claude, ChatGPT, │
                      │ Cursor, Codex        │
                      └──────────────────────┘

Your sync service keeps the server's local vault current. The server reads and edits those files, and your AI apps connect through the HTTPS service.

Quick start

Run the server on a computer that has a local copy of your vault. For guided setup with a coding agent, use SETUP-PROMPT.md.

1. Run the server

With Bun installed, run these commands. Replace the vault path and password with your own values.

git clone https://github.com/nweii/obsidian-remote-mcp.git
cd obsidian-remote-mcp
bun install
export VAULT_PATH=/absolute/path/to/your/vault
export MCP_CLIENT_ID=my-vault-mcp
export APPROVAL_PASSWORD=pick-a-password
export HOST=127.0.0.1
bun run src/server.ts

The server listens on port 3456. MCP_CLIENT_ID is a name you choose and enter in clients that ask for one. If you already use containers, follow the Docker Compose setup.

2. Expose it over HTTPS

Use a reverse proxy or tunneling service to give the server an HTTPS URL. It receives encrypted connections from clients and forwards them to http://127.0.0.1:3456 on this computer.

Tailscale Serve is also available for clients inside your private Tailscale network. Cloud-hosted connectors generally need Funnel's public URL.

Keep port 3456 private so clients use the HTTPS URL. A direct connection skips your HTTPS service and its login checks. The command above sets HOST=127.0.0.1 for this purpose; the Docker example restricts the published port instead.

Once your HTTPS service is running, stop the MCP server with Ctrl+C. Set its public address in the same terminal and restart it.

export MCP_BASE_URL=https://mcp.example.com
bun run src/server.ts

Replace the example address with your own. See HTTPS setup for the full examples and optional Cloudflare Access login protection.

3. Connect a client

Give your client the HTTPS address with /mcp added, such as https://mcp.example.com/mcp.

Use client setup for Claude, ChatGPT, Cursor, Codex, and scripts. Clients can use browser OAuth or an API key, depending on what they support.

Once connected, ask the client to read a note you know by title. To use the Obsidian CLI tools, allow Control the Obsidian app when approving the connection.

Optional features

Each one needs setup before use.

• Enable Obsidian CLI tools to query Bases, work with tasks, and use other app features. Obsidian must be running on the same computer. The server doesn't apply .mcpignore to CLI searches.

• Connect a local QMD index to search notes by meaning, not only by exact words. QMD must be running on the same computer. The server applies .mcpignore to QMD results.

• Install URL clipping to save web pages as notes with your Web Clipper templates. The server reads them from an exported Web Clipper settings file.

• Add a decision-model API key (TypeSafe, OpenRouter, or OpenAI) to skim selected notes for the passages relevant to what you're looking for. After you approve a plan, the server sends the selected note text to that model provider.

• Set up Obsidian Headless sync to keep the server's vault current without the desktop app.

Security and scope

Clients authenticate with OAuth or an API key. Browser sign-in lets you choose whether each connection can edit notes or control the Obsidian app. You can also make the whole server read-only with VAULT_READ_ONLY=true.

Vault file access is confined to the vault folder. .mcpignore blocks notes from file reads, edits, and searches. Optional CLI access has a separate .mcpignore limitation to review before enabling it.

Connected clients receive the notes they request. The optional skim tool can also send selected note text to a model provider after you approve a plan. Audit logs can contain paths and search queries; use LOG_ENABLED=false to disable logging.

Guides and reference

Similar projects

obsidian-web-mcp is another remote MCP server for Obsidian vaults, written in Python.

Tests

bun run test
bun run typecheck
bun run lint