NoteMesh

Talk to your Obsidian vault from an AI assistant.

NoteMesh is a self-hosted MCP server for your Obsidian vault. It joins your vault
as another sync client — either through Obsidian
Sync using Obsidian's official headless sync
client, or through any git
remote — so the server keeps a live, continuously-updating copy of your notes.
It then exposes that vault over
the Model Context Protocol, so MCP clients
(Claude, Codex, ChatGPT, MCP Inspector, …) can search, read, and edit your notes.
Anything an assistant writes syncs back to your other devices the same way an
edit from your phone would.

Deploy it to Railway and it's a private, single-user
server that only you can connect to.

Requirements: a place to run it, plus one way for the vault to reach the
server — either an Obsidian Sync subscription or a git repository holding your
vault. You pick which during setup.

With the git backend every change an assistant makes lands as its own commit,
authored as notemesh, so git log --author=notemesh shows you exactly what it
did and any of it can be reverted.

NoteMesh is an independent, unofficial project. It is not affiliated with,
endorsed by, or sponsored by Obsidian. "Obsidian" and "Obsidian Sync" are
trademarks of their respective owners; they are used here only to describe
what this software interoperates with.

What your MCP clients can do

The tool surface mirrors the official Obsidian CLI's vault commands:

* delete_note is enabled by default, and can be turned off on the Settings
tab. Deletions are recoverable: Obsidian Sync keeps version history, and a
git-backed vault keeps the file in the previous commit.

* Obsidian Sync doesn't send the .obsidian config folder unless asked, so
linking a vault also runs ob sync-config --configs core-plugin-data, which
brings over daily-notes.json — the file daily_note reads for your folder and
filename format. Without it the tool would fall back to YYYY-MM-DD at the vault
root and quietly build a second set of dailies beside your real ones. Nothing to
configure here: change it in Obsidian and it follows on the next sync. A vault
linked before this existed, or a git repo without .obsidian committed, gets
the Obsidian defaults; the Settings tab says which of the two you have.

The Tools tab in the admin UI lists the same tools with their full
descriptions and parameters. That page asks the running server over the
protocol, so it is what your client is actually offered — this table is a
summary, and the tab is the answer.

Everything an MCP client writes lands in the synced vault folder and propagates
to your other devices — through Obsidian Sync (end-to-end encrypted, as always),
or as a commit pushed to your git remote.

Deploy on Railway

The button is the whole path: the published template carries the volume, a
generated ENCRYPTION_KEY, the healthcheck and a public domain, so you land on
the setup wizard with nothing to configure.

TEMPLATE.md is the full guide — Part
B covers deploying and living with
it, including sizing the volume and troubleshooting; Part
A covers publishing a template of
your own.

Git-backed vaults

Pick Git repository during setup and any HTTPS remote works — GitHub,
GitLab, Gitea, self-hosted. Give the clone URL, the branch, and a token scoped
to that one repo (on GitHub: a fine-grained PAT with Contents: read and write).

How it behaves:

• Writes land on disk immediately, then batch into one commit and push after
  a few seconds of quiet — configurable on the Settings tab, and forced at least
  every 30 seconds so a busy assistant can't defer it indefinitely.

• Commits are attributable. Each is authored notemesh <notemesh@localhost>
  with the tool names in the subject and the paths in the body, so
  git log --author=notemesh is a complete record of assistant activity.

• Conflicts are checked for before anything is written. The server runs
  git merge-tree, which performs the merge inside git's object database and
  reports conflicts without touching the working tree. Concurrent edits to
  different notes — or to different parts of the same note — merge cleanly and
  keep both sides, with no conflict handling involved at all.

  The only case that needs a decision is the same region of the same note
  changing on both sides at once, and the Settings tab chooses what happens
  then:

  Strategy	What you get
  Generate conflict file (default)	Your devices' version keeps the real filename; the assistant's is saved beside it as Note (Conflicted copy notemesh 202608031958).md and synced to every device — the same convention Obsidian Sync uses
  Place conflicts on a branch	Vault left untouched and matching the remote; the assistant's version kept on notemesh/conflict-<timestamp>, recoverable with git merge
  Inline git-style markers	Both versions in the note separated by <<<<<<< — faithful to git, but the assistant reads your notes and will treat the markers as content

  Under the first two, conflict markers never enter the vault at all. Nothing is
  ever discarded under any of the three.

• Attachments. git handles large binaries poorly, so this suits
  markdown-heavy vaults. git-lfs is installed in the image, so LFS-backed
  repos work; if an LFS object is ever missing, reads fail loudly rather than
  serving you a pointer file dressed up as an image.

Requires git 2.38+ for merge-tree (the image ships 2.47). SSH remotes aren't
supported yet.

Tests

pnpm test

243 tests across nine files. Anything touching git runs against the real git
binary in throwaway repositories rather than mocks — the behaviour under test
is git's merge behaviour, so stubbing it would prove nothing.

The security tests are mutation-checked: deleting a guard has to make specific
tests fail, or the test wasn't testing it.

Connect MCP clients

The MCP endpoint is https://<your-app>/api/mcp (Streamable HTTP). The
Setup tab shows all of this filled in with your own URL, with copy buttons —
what follows is the same thing for reference.

• Claude (web, Desktop, Cowork) — add it as a custom connector, not an
  .mcpb bundle. Bundles package local stdio servers; NoteMesh is a remote
  Streamable HTTP server, which is what custom connectors are for. Configure it
  once at claude.ai → Customize → Connectors → Add custom connector → paste
  the endpoint URL, and it becomes available across your Claude surfaces. The
  OAuth flow redirects to your server; approve on the consent screen.

  This requires a public HTTPS URL. Anthropic's infrastructure makes the
  connection, not your machine, so http://localhost:3000/api/mcp will not work
  as a custom connector — deploy to Railway first and use that URL. (Claude Code
  and Codex run locally and can reach localhost, which is why they work
  against a dev server.)

• Claude Code:

  claude mcp add --transport http notemesh https://<your-app>/api/mcp
  

• Codex — add to ~/.codex/config.toml, then codex mcp login notemesh:

  [mcp_servers.notemesh]
  url = "https://<your-app>/api/mcp"
  auth = "oauth"
  default_tools_approval_mode = "approve"
  

  default_tools_approval_mode = "approve" lets the tools run without
  approving each call. Worth setting: without it Codex prompts per call, and
  because its reported per-call timings are wall-clock, the seconds you spend
  approving are counted as tool latency — which reads as a slow server. A call
  left unapproved long enough also hits Codex's own timeout and can knock the
  whole tool schema out of its session.

• Anything with a bearer token — create an API key on the Setup tab and
  send it as Authorization: Bearer <key> (or x-api-key: <key>).

How writes propagate (read this before testing)

The server keeps its own replica of your vault at $DATA_DIR/vault. MCP
write tools use synchronous filesystem writes, so a change is on the server's
disk before the tool returns — measured at ≤0.2 ms over 40 consecutive writes.

Reaching your other devices is a separate step: the ob sync daemon uploads
the change and each device downloads it. That round-trip is seconds to
minutes and batches multiple edits together.

This matters when verifying a write. If you check a different copy of the vault
— your desktop Obsidian vault, say — the change is legitimately absent until
sync delivers it, which looks exactly like a write that never flushed. Verify
against the path reported by get_vault_info (vaultPath), not another copy.

Size limits

read_note returns {totalLines, offset, count, hasMore} alongside content,
so a long note is paged with offset rather than dumped in one response — a
465 KB note would otherwise be ~121k tokens in a single tool call.

Binary files are refused by the text read path (detected by content, not just
extension) and served by read_attachment, which returns images as viewable
image content. Anything over 1 MB is not inlined; the result carries a
short-lived signed URL instead, which is a direct download for you rather than
something the model can see — MCP clients do not fetch links out of tool
results. Reading a JPEG as
text previously produced a 12 MB response of replacement characters.

Security model

• Credentials stored depend on the backend. Obsidian Sync needs your account
  password, because the sync client re-authenticates with it. Git needs only a
  scoped access token for one repository, which you can revoke without
  touching anything else. Both are AES-256-GCM encrypted at rest.
• Single-user: exactly one admin account. Sign-up is open only while the
  instance is unclaimed and the process has been up for less than 30
  minutes; after that the server locks down and a restart is required to
  reopen the window. Once claimed, sign-up closes permanently.
• The server holds your Obsidian account credentials and the vault E2E
  password (AES-256-GCM encrypted with a key derived from ENCRYPTION_KEY) so
  the sync daemon can re-authenticate. Treat the Railway project as sensitive.
• The built-in OAuth 2.1 authorization server (Better Auth) supports PKCE and
  dynamic client registration; every client authorization requires your
  explicit approval while signed in as admin.
• MCP tool access is scoped (vault:read / vault:write); note deletion is an
  opt-in setting on top of that.
• Path traversal, symlinks, and the .obsidian config directory are blocked
  from all MCP file operations.
• Only failed authentication is throttled. A request carrying a valid API key
  or OAuth token is never rate-limited, so a busy agent is unaffected; the limit
  exists to damp anonymous probing.

The Security tab renders this as the live state of your instance rather than
prose: whether you're on HTTPS, whether client IPs are visible to the throttle,
how many keys/clients/tokens currently hold access, what's being blocked right
now, and which endpoints are exposed with what auth.

Local development

pnpm install
cp .env.example .env   # fill in ENCRYPTION_KEY (openssl rand -base64 32)
pnpm dev

Visit http://localhost:3000/setup. Without an Obsidian account you can still
exercise the MCP endpoint: drop some .md files under data/vault/, mark the
instance configured (sqlite3 data/app.sqlite "INSERT INTO settings (key,value) VALUES ('vault_configured','true')"), create an API key from the dashboard,
and point MCP Inspector
at http://localhost:3000/api/mcp.

Architecture

One Node process (SolidStart) plus one supervised child process:

• SolidStart app — admin dashboard, setup wizard, OAuth authorization
  server (Better Auth + oauth-provider plugin), and the MCP endpoint
  (@modelcontextprotocol/sdk, stateless Streamable HTTP).
• ob sync --continuous — the official Obsidian Headless client, spawned
  and supervised with backoff/re-auth detection. HOME is pointed at the
  volume so its session survives restarts.
• SQLite (/data/app.sqlite) — auth tables, OAuth clients/tokens, API
  keys, settings, and an FTS5 index over the vault (rebuilt by a chokidar
  watcher on every file change) powering search, links, tags, and tasks.

Licence

Copyright © 2026 ChangeNode (Will Iverson). See COPYRIGHT.

NoteMesh is dual-licensed.

• AGPL-3.0 for everyone. Free to use, modify, and self-host.
  Running your own instance triggers no obligation — it is single-user by
  design, so you are the only user of your service and you already have the
  source.
• A commercial licence if you want to offer NoteMesh to other people as a
  hosted service without publishing your source. See
  COMMERCIAL-LICENSE.md.

Contributions require a CLA so that arrangement keeps working — see
CONTRIBUTING.md.

Note that the Obsidian Sync backend spawns Obsidian's official headless client,
which npm publishes as UNLICENSED (proprietary, Dynalist Inc.). Nothing here
relicenses it: it is run as a separate process and installed from npm by
whoever deploys NoteMesh.