Allows an LLM to search, read, and write notes in an Obsidian vault organized with the PARA method, including saving URLs as notes.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@vault-mcp save this URL to my 01-Inbox for later"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A small remote MCP server that lets an LLM (claude.ai, Claude Code, mobile) search, read, and write an Obsidian vault organised with the PARA method — and save URLs as notes.
The server holds no LLM of its own. It is a deterministic set of tools; the
connecting model is the brain. When you ask it to "save this to my vault", the
model calls vault_taxonomy to see your folder structure, picks the right
folder itself, and calls vault_write.
Claude Desktop / claude.ai / Claude Code
│ HTTPS + GitHub OAuth (or Bearer token)
▼
reverse proxy / TLS ──► vault-mcp (this server) ──► ~/Obsidian/YourVaultDocs: Architecture · Authentication · Deployment · Changelog
Tool | What it does |
| Returns the folder tree, PARA policy, and subcategory whitelists so the model can choose a destination folder. |
|
|
| Returns a note's content. Machine-generated index/log files and legacy dumps are blocked. |
| Create / overwrite / append a note. The caller supplies the folder. Writes are restricted to PARA buckets; the vault root is never written. |
| Fetch a URL, extract clean text, save it as a note, and return a small preview. |
Related MCP server: mcp-obsidian-second-brain
Every path is resolved and confined to the vault root — no .. traversal, no absolute paths, no symlink escapes.
Writes are allowed only under 01-Inbox/, 10-Projects/, 20-Areas/, 30-Resources/, docs/.
Reads of regenerable index/map/log artifacts and legacy wiki backups are refused (they are huge and waste tokens).
Auth is required: a static Bearer token or GitHub OAuth with a user allowlist (see Authentication).
git clone https://github.com/KORThomasJeong/vault-mcp.git
cd vault-mcp
cp .env.example .env # then edit .env
uv syncGenerate an auth token:
python -c "import secrets; print(secrets.token_urlsafe(32))"All config is via environment (see .env.example):
Var | Required | Default | Notes |
| ✅ | — | Absolute path to the vault root. |
| inferred |
| |
| (none) | Bearer token (token mode). | |
| (none) | GitHub OAuth app credentials (github mode). | |
| (none) | Public HTTPS URL of the server (github mode). | |
| (none) | Comma-separated GitHub logins allowed to connect. Required in github mode. | |
|
| Use | |
|
| ||
|
| ||
| (none) | Warm semantic-search front-end, called | |
|
| Fallback semantic search helper. Blank + no | |
|
| Title/path search helper. Blank → disabled. | |
|
| URL→note helper. Blank → disabled. | |
| (none) | Command run when a tool is called with |
The search and URL-save tools shell out to optional companion CLIs. If you don't have them, those tools simply report that they're disabled — read/write/taxonomy still work.
uv run vault-mcp
# serves Streamable HTTP at http://127.0.0.1:8848/mcpExpose it through your existing reverse proxy (nginx / Nginx Proxy Manager /
Caddy / Cloudflare) so that https://your-host/mcp forwards to 127.0.0.1:8848.
Enable WebSocket/streaming pass-through and disable response buffering so SSE
works (for nginx: proxy_buffering off;, a long proxy_read_timeout).
Mode | How clients authenticate | Works with |
|
| Claude Code ( |
| GitHub OAuth (browser), restricted to | Claude Desktop / claude.ai remote connectors, Claude Code. |
| nothing | trusted/private networks only. |
| both at once (MultiAuth) | Desktop via OAuth and CLI/automation via token, one server. |
OAuth authenticates, the allowlist authorizes. In
githubmode the server refuses to start unlessGITHUB_ALLOWED_USERSis set — otherwise any GitHub account could connect, which is more open than a token.
Both at once: set
MCP_AUTH_TOKENalongsidegithubmode and the server accepts GitHub OAuth and the static token simultaneously (MultiAuth). Details in docs/AUTHENTICATION.md.
Register an OAuth App at https://github.com/settings/developers → New OAuth App:
Homepage URL: https://your-host
Authorization callback URL: https://your-host/auth/callback
Copy the Client ID, generate a Client secret, and put them plus
BASE_URL=https://your-host, AUTH_MODE=github, and
GITHUB_ALLOWED_USERS=<your-login> in .env.
Restart the server.
# token mode
claude mcp add --transport http vault https://your-host/mcp \
--header "Authorization: Bearer <your-token>"
# github mode (OAuth — opens a browser)
claude mcp add --transport http vault https://your-host/mcpSettings → Connectors → add a custom connector pointing at https://your-host/mcp.
Use github mode — the desktop/web connector UI authenticates via OAuth and
has no field for a static Bearer token.
uv run --extra dev pytestMIT
This server cannot be deployed
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
