Watch the Remote Vault Bridge in 44 seconds

Remote setup guide

Remote request → semantic search → graph context → guarded edit → mount-loss recovery.

Obsidian Everywhere is built around two ideas:

1. Notes are a graph and a semantic knowledge base, not a folder of text
   files. Backlinks, n-hop neighborhoods, shortest paths, PageRank, full-text
   search, and local multilingual embeddings turn a topic into focused,
   token-budgeted context.
2. Your vault should be usable where your agents run. The Remote Vault
   Bridge exposes that same graph and its guarded write tools over authenticated
   Streamable HTTP. A Claude Code or Codex process on another server can search,
   reason over, append to, and reorganize a vault that remains on your own
   machine.

The local path stays the source of truth. There is no hosted copy, telemetry
service, or mandatory cloud account. Remote access is a transport you operate,
not a vault-sync product.

Contents

• Watch the Remote Vault Bridge in 44 seconds
• Features
• Two core capabilities
• Try it without your vault
• Why Obsidian Everywhere?
• Where does this actually run?
• Quickstart
• Configuration
• Development
• Project status
• Contributing
• License

Features

vault (.md files)
  │  parse · watch
  ▼
SQLite index (FTS5)  ⇄  in-memory graph (graphology)
  │                       n-hop · shortest path · PageRank
  ▼
41 MCP tools
  │
  ▼
local stdio  ·  authenticated remote HTTP  ·  OAuth HTTP

• 🧩 Graph + semantic context engine — a markdown parser (wikilinks, embeds,
  frontmatter, nested tags, headings, block references), a SQLite index
  with full-text search, and an in-memory graphology
  layer for n-hop traversal, shortest paths, and PageRank. get_context_bundle
  packs a topic and its most useful neighbors into a requested token budget.
• 🌍 Remote Vault Bridge — agents on an external server get the same search,
  graph, context, and guarded editing tools over authenticated Streamable HTTP.
  Use a private network or an HTTPS tunnel such as ngrok; the vault itself stays
  on the machine you control.
• 📎 Vault-wide file reading — Markdown plus text/code/data files, PDF,
  DOCX, PPTX, XLSX, OpenDocument, EPUB, RTF, and common images are indexed and
  exposed without uploading them to a conversion service. Extraction is lazy,
  cached, size-limited, and searchable with search_files.
• 🧠 Optional local semantic search — semantic_search and get_related with
  method: "semantic" run a multilingual embedding model
  (multilingual-e5-small) entirely on your machine — no API key, cloud
  account, or Ollama process to run. Install the optional runtime with
  npm install @huggingface/transformers@^4.2.0; its model downloads once
  (~120MB, cached under
  ~/.obsidian-everywhere/), then works fully offline. It is disabled by
  default to keep the server below the 200 MiB memory target; opt in with
  OBSIDIAN_EVERYWHERE_ENABLE_SEMANTIC=true when extra memory is available.
• 🛡️ Safe writes and resilient mounts — partial edits, dry-run-first bulk
  operations, rollback snapshots, recoverable deletion, and an opt-in Beta
  mount guard. If a removable drive, NAS share, or container mount disappears,
  the index is preserved, writes are blocked, and a full reconciliation runs
  after it returns.
• 🛠️ 41 graph-native MCP tools — structured reads, attachment extraction, graph navigation,
  semantic retrieval, safe lifecycle operations, persisted Obsidian settings,
  and explicit vault_status health reporting.

Two core capabilities

1. Turn a linked vault into focused AI context

Exact search finds the words you wrote. Semantic search finds the idea even
when the wording or language differs. Graph traversal then explains how the
matching notes relate. get_context_bundle combines those signals into a
bounded context package instead of dumping an entire vault into the model.

2. Use and edit that context from an external server

Run Obsidian Everywhere beside the local vault, expose its HTTP endpoint through
your private network or an HTTPS tunnel, and register the URL in the remote MCP
client. The remote agent can read and search the local vault, then use the same
guarded tools to create, append, move, tag, or clean up notes. The server
reindexes each successful write before returning, so the next remote tool call
sees the change.

For the complete ngrok path, see the
Remote Vault Bridge with ngrok tutorial.

Read

Write

Write tools are on by default for stdio and the
bearer-token HTTP transport, and off by default for the public OAuth
connector transport (opt in with OAUTH_ENABLE_WRITE_TOOLS=true) — see
Configuration and DECISIONS.md D15.

Try it without your vault

Run the built-in demo first. It creates a temporary sample vault, shows graph
orientation and unresolved-link discovery, previews a safe bulk edit, and then
removes the sample. It never reads or changes your own notes.

npx -y obsidian-everywhere demo

When you are ready to connect a real vault, generate copyable configuration for
Codex, ChatGPT Desktop, Claude Code, and Claude Desktop:

npx -y obsidian-everywhere init /absolute/path/to/your/vault
npx -y obsidian-everywhere doctor /absolute/path/to/your/vault

init only prints configuration—it never edits global client settings.
doctor checks Node.js, permissions, Obsidian metadata, SQLite, parsing, and the
graph engine without printing note content. Add --share to redact the vault
path before pasting diagnostics into an issue.

Why Obsidian Everywhere?

There are several good Obsidian MCPs. Pick the architecture that matches how
you work rather than assuming one server wins every category.

Comparison checked against each project's published documentation on
2026-07-20. A blank or narrower cell means “not documented there,” not that a
project can never support it. If you need active-file state or command-palette
execution, choose a plugin-backed server. If you want a headless, one-command
graph server with token-budgeted context and guarded cleanup, that is the niche
Obsidian Everywhere is designed for.

Everything runs locally by default. There is no account, API key, hosted vault,
or telemetry requirement.

See docs/architecture.md for how it's built,
docs/deploy.md for the deployment topology, and
docs/ngrok-remote.md for an end-to-end external
server tutorial.

Where does this actually run?

The obsidian-everywhere process needs direct filesystem access to your
vault's .md files (to parse them, watch for changes, etc.) — so it
must always run on the machine where your vault physically lives
("the vault machine": your laptop, most likely). It does not matter which
client machine you're working from — the server always runs on the vault
machine; only the client connection method changes.

You can run more than one of these at once (e.g. stdio on your laptop
and bearer-token HTTP for your work server) — they're independent
processes that all index the same vault.

Quickstart

The fastest install needs no clone or build step. Run this on the vault
machine (wherever your .md files live):

npx -y obsidian-everywhere /absolute/path/to/your/vault

MCP clients normally launch this command for you using one of the
configurations below.

Not sure whether the path and runtime are ready? Run the privacy-safe diagnostic:

npx -y obsidian-everywhere doctor /absolute/path/to/your/vault

Option A — Codex CLI and ChatGPT Desktop, same machine as the vault (stdio)

Codex CLI, the Codex IDE extension, and ChatGPT Desktop's Codex experience
share the same MCP configuration (official MCP documentation).
Add the server once:

codex mcp add obsidian-everywhere -- npx -y obsidian-everywhere /absolute/path/to/your/vault
codex mcp list

Then restart ChatGPT Desktop (or the IDE extension). In ChatGPT Desktop you
can also add it through Settings → MCP servers → Add server, choose
STDIO, and enter the same command and arguments. Type /mcp in Codex to
confirm that the server and its 39 tools are connected.

For a project-scoped configuration instead, add this to a trusted project's
.codex/config.toml; use ~/.codex/config.toml to make it available globally:

[mcp_servers.obsidian-everywhere]
command = "npx"
args = ["-y", "obsidian-everywhere", "/absolute/path/to/your/vault"]
startup_timeout_sec = 30

Use an absolute vault path. GUI apps may not inherit the same PATH as your
terminal; if npx is not found, replace command with the absolute result
of command -v npx.

Option A′ — Claude Code, same machine as the vault (stdio)

Still on the vault machine:

claude mcp add obsidian-everywhere -- npx -y obsidian-everywhere /path/to/your/vault

Or with environment variables instead of a positional arg:

OBSIDIAN_VAULT_PATH=/path/to/your/vault claude mcp add obsidian-everywhere -- npx -y obsidian-everywhere

Option A″ — Claude Desktop, same machine as the vault

Add to claude_desktop_config.json on the vault machine:

{
  "mcpServers": {
    "obsidian-everywhere": {
      "command": "npx",
      "args": ["-y", "obsidian-everywhere", "/absolute/path/to/your/vault"]
    }
  }
}

Option A‴ — Google Antigravity CLI (agy)

Add to your global Antigravity MCP configuration file (~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "obsidian-everywhere": {
      "command": "npx",
      "args": ["-y", "obsidian-everywhere", "/absolute/path/to/your/vault"]
    }
  }
}

Option B — Codex, ChatGPT Desktop, or Claude on a different machine

Choose one secure route to the vault machine:

• Private network: use Tailscale and follow the steps below.
• Public HTTPS tunnel: use the read-only-first
  ngrok Remote Vault Bridge tutorial. Never expose
  the local plaintext HTTP port directly.

Step 1 — set up a private network between the two machines, if you chose
Tailscale:

# on BOTH the vault machine and the MCP client machine
curl -fsSL https://tailscale.com/install.sh | sh   # or: brew install tailscale (macOS)
tailscale up                                        # opens a browser to log in / join your "tailnet"
tailscale status                                    # confirm both machines can see each other

Note the vault machine's Tailscale hostname/IP from tailscale status
(something like my-macbook.tailnet-name.ts.net or 100.x.y.z).

Step 2 — start the server, on the vault machine:

OBSIDIAN_VAULT_PATH=/path/to/vault OBSIDIAN_EVERYWHERE_TOKEN=$(openssl rand -hex 32) \
  npx -y --package obsidian-everywhere obsidian-everywhere-http

Keep this token — you'll need it in step 3. (To keep this running
persistently instead of in a foreground terminal, see the LaunchAgent
setup in docs/deploy.md,
or run it in Docker via docker-compose.yml if the vault machine is a server.)

Step 3 — connect from the other machine (the lab server, etc.), using
the vault machine's Tailscale address from step 1. For Codex (and the shared
ChatGPT Desktop configuration), keep the token in an environment variable:

export OBSIDIAN_EVERYWHERE_CLIENT_TOKEN="<the token from step 2>"
codex mcp add obsidian-everywhere \
  --url http://<vault-machine-tailscale-name>:3737/mcp \
  --bearer-token-env-var OBSIDIAN_EVERYWHERE_CLIENT_TOKEN

Ensure ChatGPT Desktop is launched with that environment variable available,
then restart it. Alternatively, use Settings → MCP servers to add the
Streamable HTTP URL and bearer credential if your app version exposes those
fields.

For Claude Code:

claude mcp add --transport http obsidian-everywhere \
  http://<vault-machine-tailscale-name>:3737/mcp \
  --header "Authorization: Bearer <the token from step 2>"

The second machine now has access to the vault indexed on the first. Full
walkthrough (Docker, LaunchAgent):
docs/deploy.md.

Option C — claude.ai web/mobile app (custom connector, OAuth)

This needs a public HTTPS endpoint — claude.ai's servers can't reach your
Tailscale network or localhost. See
docs/deploy.md
for the full Cloudflare Tunnel walkthrough (including the no-domain-needed
Quick Tunnel option for testing). Once your server is reachable at
https://your-domain:

1. claude.ai → Settings → Connectors → Add custom connector
2. Server URL: https://your-domain/mcp
3. claude.ai auto-discovers the OAuth flow and shows this server's sign-in
   page — enter the OAUTH_LOGIN_SECRET you configured.

You only need this if you actually want claude.ai's web/mobile apps to
read your vault. If you only ever use Claude Code (locally or from
another machine), skip this entirely — Option A/B already fully covers
that with no Cloudflare/OAuth involved.

Configuration

Development

npm run dev:stdio          # tsx, no build step
npm run dev:http
npm run dev:oauth-http
npm test                   # vitest, runs against fixtures/test-vault
npm run typecheck
npm run lint
npm run format:check
npm run memory:smoke      # asserts the default attachment workload stays below 200 MiB RSS

fixtures/test-vault/ is a 30+ note fixture vault exercising every link
and parsing edge case the parser needs to handle (piped aliases, heading
and block links, embeds, frontmatter-embedded wikilinks, nested tags,
duplicate filenames across folders, unresolved links, code-block
exclusion, and Korean filenames/tags/wikilinks). It's what every test in
src/**/*.test.ts runs against.

Project status

Current v0.8.0 includes the graph and optional local semantic context engine, all three
transports (stdio, bearer HTTP, OAuth HTTP), 41 MCP tools, guarded partial and
bulk writes, and client setup for Codex, ChatGPT Desktop, and Claude. Remote
Vault Bridge is a first-class deployment path. Its opt-in mount guard remains
Beta while it receives cross-platform feedback for removable drives, NAS
shares, and container mounts.

Help test a real remote-vault setup in
Beta Issue #18,
or ask questions in
Discussion #19.
A disposable vault is welcome; never share note contents, tokens, or private
hostnames.

Contributing

Bug reports, feature requests, and PRs are welcome — see
CONTRIBUTING.md for dev setup, testing conventions,
and how the fixture vault relates to the test suite. Security issues:
please see SECURITY.md rather than opening a public issue.

License

MIT — see LICENSE.