Obsidian MCP Server

Stack: Python 3.12, FastAPI, PostgreSQL with pgvector. Pluggable embeddings (Ollama bge-m3, or OpenAItext-embedding-3-{small,large}).

There are three things going on here, and they're more interesting together than apart.

1. A shared memory layer between you and your agents

I think of my Obsidian vault as my exocortex. The "big me" that includes notes, calendars, scripts, search, and AI assistants is substantially more capable than the "small me" of the biological brain alone. It's also where I do most of my thinking, because writing something down is itself a form of thought.

The problem is that until recently, the vault was passive. I had to go find things. Agents that wanted to help me had to be briefed from scratch every session, and they had no way to see what I'd already written about a topic.

This server fixes that. Now the same vault feeds my own daily writing and any agent I plug into it. The agent reads what I read, links what I link, follows the same wikilinks, sees the same frontmatter. When I write a project note on Sunday, my Monday-morning briefing agent already knows about it. When the agent leaves notes from a research session, they show up in my normal Obsidian search.

A concrete version of this: I'll spend a session in Claude Code on a project, wrap up, push the commits, and then just say "update Obsidian." The agent reads the vault guide, figures out where project notes live in my structure, picks the right format and frontmatter, and leaves a session log I can later roll into a status report. No path-passing, no telling it what to write — the conventions are already in the vault, and it follows them.

That's the exocortex idea made concrete: one place that holds context, and both the human and the agents reading and writing into it on the same terms.

2. Agent memory that you can actually read

The other half is the inverse. If you let an agent run for a while, it needs memory. Most setups solve this with an opaque vector store, a SQLite blob, or a managed "memory" service that you can't see into. That works until you want to know what the agent thinks it knows about you, or you need to correct something, or you want to understand why it just made a weird suggestion.

This server gives you a different deal. Agent memory lives as markdown files in your vault. Folder structure, file names, frontmatter, all visible. You can open the file in Obsidian and read it. You can edit it. You can delete it. You can grep it. The agent's "memory" is a human-auditable artifact that sits in the same place as your own notes, with the same tools available.

The home lab is the use case that sold me on this. My vault has notes on the rack, the network, and every Home Assistant integration. I can say "set up a night-light mode in the master bathroom, 1% after 11pm" and a sysadmin agent finds the right config, makes the change, and updates the doc in the same pass. Six months later when I've forgotten how it works, the answer is in the vault, not buried in some chat history I can't search.

The semantic search and wikilink graph still work over that material, so retrieval is fast and conceptual. But the substrate is files you own, not a black box.

The thing that still surprises me is that this is internet-facing. Same vault, same notes, reachable from anywhere I happen to be talking to an agent — Claude in a browser tab, Claude on my phone on the train, an n8n workflow firing on a schedule, a Claude Code session on whatever laptop is in front of me. All behind OAuth or a bearer key, all hitting the same source of truth.

So when I hear an interesting podcast on a commute and want to think out loud about it with Claude on my phone, the agent isn't starting cold. It can pull up what I've already written on adjacent topics, surface a note I half-finished six months ago, and at the end of the conversation suggest updates and write them in. The vault doesn't have to be near me to be the thing I'm working in.

To make the abstract concrete, a short transcript from a real session. Tool calls inline; the user types in plain English and the agent picks the right tool.

The bundled Caddy configuration fails closed on/admin,/api, and/authorize; replace its placeholder basic-auth hash before starting it.

- Docker and Docker Compose
- A PostgreSQL 16 instance reachable from the container, with thepgvectorextension installed
- Either an Ollama instance runningbge-m3, or an OpenAI API key. Anything that speaks the OpenAI embeddings protocol works (Azure OpenAI, OpenRouter, Together, etc.).

1. Clone, configure, point at your vault

git clone https://github.com/maxkuminov/obsidian-mcp.git cd obsidian-mcp cp .env.example .env $EDITOR .env

Indocker-compose.yml, point the/obsidianvolume at your vault:

volumes: - /path/to/your/vault:/obsidian

EMBEDDING_PROVIDER=openai OPENAI_API_KEY=sk-... EMBEDDING_DIMENSIONS=1024 OPENAI_EMBEDDING_MODEL=text-embedding-3-small

The server validatesOPENAI_API_KEYat startup and refuses to boot if it's missing.

Option B, Ollama (self-hosted, GPU recommended):

EMBEDDING_PROVIDER=ollama OLLAMA_URL=http://your-ollama-host:11434 EMBEDDING_MODEL=bge-m3 EMBEDDING_DIMENSIONS=1024

This is the default. OmittingEMBEDDING_PROVIDERfalls back to Ollama.

make init # data dirs and .env from template (skip if you've already edited) make db-init # create database, user, and pgvector extension make deploy # build, push to local registry, run migrations, recreate container

The first deploy backfills the index, the wikilink graph, and the embeddings. For a 2 to 3k-note vault on Ollama with a GPU this takes a few minutes. Ontext-embedding-3-smallit's seconds.

Mint an API key in the control panel, then point your MCP client at:

URL: https://obsidian-mcp.<your-domain>/mcp Auth: Bearer omcp_...

For Claude Desktop, add toclaude_desktop_config.json:

{ "mcpServers": { "obsidian": { "url": "https://obsidian-mcp.<your-domain>/mcp", "headers": { "Authorization": "Bearer omcp_..." } } } }

claude mcp add obsidian --transport http \ --url "https://obsidian-mcp.<your-domain>/mcp" \ --header "Authorization: Bearer omcp_..."

The first thing any agent should do in a new session is callget_vault_guide(). That's how it learns your folder structure, naming conventions, and YAML schema before it writes anything.

If you go the OpenAI route (the realistic path on a CPU-only VPS), the first-index spend is small and the steady state is nearly free. Rough numbers assuming an average note around 1,500 tokens (three 512-token chunks), at OpenAI's published rate at time of writing:

After the first index, only changed notes are re-embedded. Ongoing cost is proportional to edits — pennies a month for a typical vault.

If you self-host Ollama with a GPU, embedding cost is whatever your power bill is. Ollama on CPU works but is too slow to be usable on a vault of more than a few hundred notes.

This is the part most "MCP for Obsidian" projects miss. They stop at read, write, and list. The interesting question isn't "can the agent reach the files," it's "does the agent know the rules?"

If you have an opinionated vault — task placement logic, folder conventions, required frontmatter, tag taxonomy — an agent with write access can do real damage without that context. Tasks land in the wrong folder. Bare-date filenames collide with templates. Wrong tags break Dataview queries. The data layer works fine; the context layer is where the failures show up.

The fix is small. Keep a machine-readable instruction file (CLAUDE.mdat the vault root) that describes the system's own rules. Expose it as a dedicated tool. Every connecting agent calls it once at the start of a session and immediately knows how the vault works. Update the file, every agent sees the change on the next call. No client-side config. No system-prompt injection. The vault is authoritative about its own rules.

get_vault_guide()does exactly this. It returns a generic Obsidian primer (wikilink syntax, embed syntax, tag conventions, common plugin literals) plus the vault'sCLAUDE.mdlive. The hint to call it first is baked into the write-tool descriptions so the agent gets pulled into the right behavior even without prompting.

Single-user mode is the default and works exactly as described above — one vault, one set of API keys, no in-app user concept. Multi-user mode is an opt-in flag that turns the same container into a small multi-tenant deployment: in-app username/password login, per-user vault scoping, an admin role for troubleshooting, and a regular-user role that sees only its own keys/OAuth clients/usage. One container, one Postgres, strict isolation between users.

Enable it on an existing deployment with no data loss — your current vault and keys carry over to the bootstrap admin.
- SetMULTI_USER_MODE=trueand a strongSECRET_KEYin.env(openssl rand -hex 32is fine). The app refuses to start with the placeholder value when the flag is on.
- make deploy(ordocker compose up -d --force-recreate).
- Visit the panel. Because theuserstable is empty, you're routed to/admin/register— the one-time bootstrap form. It's still behind Traefik'schain-oauth@filemiddleware, so only people Traefik already trusts can claim admin.
- Register with a chosen username and password. The bootstrap form pre-fillsvault_pathwith whateverVAULT_PATHwas set to, so your existing notes immediately belong to this new admin. No re-index, no re-embed, no data loss — every previously indexed note, API key, OAuth client, and usage log row gets backfilled to the bootstrap user in a single transaction.
-

Editdocker-compose.ymlto add a volume mount for the new user's vault under/vaults/<username>. Host paths with spaces must be quoted as a single YAML string:

volumes: - "/storage/vaults/alice:/vaults/alice" - "/storage/shared/bob/Obsidian:/vaults/bob"

In the panel,/admin/users/create— pick a username and set an initial password.

/admin/users/{id}/edit— set the user'svault_pathto the container path you just mounted (e.g./vaults/bob). The form shows a dropdown of unassigned/vaults/*directories that exist on disk.

Share the credentials out-of-band. The user logs in at/admin/auth/login, gets their own keys/OAuth/usage views, and cannot see other users' notes.

Admins see API keys, OAuth clients, and usage logs for all users; they own the Settings page (embedding provider, indexer trigger, danger zone) and the Users page. Admins donotbrowse other users' vault contents through the panel — that's intentional. Troubleshooting another user's vault means either inspecting it viadocker execor temporarily reassigning theirvault_path, not UI snooping.