mcp-obsidian
MCP server (Rust) for writing, reading, searching, and mapping per-project memory into an Obsidian Vault.
Potencia tu agente
Instalación del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
Aún no hay una versión empaquetada en el registro. Sigue el README del repositorio.
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDel publicador
MCP server (Rust) for writing, reading, searching, and mapping per-project memory into an Obsidian Vault.
MCP server (Rust) for per-project memory in an Obsidian vault — plain Markdown, no database
Each memory is stored as a plain Markdown file with YAML frontmatter, so it can be opened, linked, and visualized directly in Obsidian (Graph View, tags, backlinks). No database — your vault stays portable.
The server exposes all three MCP capabilities: tools (CRUD + analysis), resources (each memory can be attached as context), and prompts (ready-to-use workflows based on memory content).
<Obsidian Vault>/
├── memory/ # OBSIDIAN_MEMORY_ROOT (default: "memory")
│ ├── project-a/ # one folder per project
│ │ ├── _MOC.md # map (Map of Content) — auto-generated
│ │ ├── auth-flow.md # one memory = one note
│ │ └── deploy-pipeline.md
│ └── project-b/
│ └── ...
└── docs/ # OBSIDIAN_DOCS_ROOT (default: "docs")
└── project-a/ # long documents, SEPARATE from the memory graph
├── _DOCS.md # document index — auto-generated
├── login-spec.md # spec / runbook / brainstorm / worklog
└── sprint-log.md
Memory vs document. A memory is an atomic, interlinked fact that is indexed
into the graph, semantic search, and _MOC.md. A document is a long note
(spec, runbook, brainstorm, worklog) stored in a separate root and deliberately
not indexed — so that long text does not pollute the quality of search and the
map. For that reason, documents are found via doc_list/doc_search, not
semantic search.
Example contents of a single memory (auth-flow.md):
---
name: auth-flow
description: How authentication works
tags:
- auth
- security
type: project
links:
- deploy-pipeline
created: 2026-05-30T22:40:00+07:00
updated: 2026-05-30T22:40:00+07:00
---
Use JWT. See [[deploy-pipeline]].
_MOC.md is rebuilt automatically whenever something changes: grouped by
category (type), plus the sections 🔗 Relations (outgoing links),
⬅️ Backlinks (incoming links, auto-counted), 🏷️ Tag Index,
💡 Suggested Relations, and 🧩 Themes (community clusters).
docs/ folder, not indexed into the graph)Default mode per type: brainstorm/worklog → append, spec/runbook → overwrite.
On every tool, the project argument is optional. If empty, the project is
determined in order from: the argument → OBSIDIAN_DEFAULT_PROJECT → the name
of the working directory where the server is run.
Memories and documents are exposed as URI-addressed MCP resources, so clients can list and "attach" their contents directly as context without calling a tool.
MIME type: text/markdown. Browse via resources/list & resources/read.
The _DOCS.md index is regenerated automatically on every doc_write/doc_append/doc_rename/doc_delete.
Three ready-to-use prompts that assemble context from memory content. All
accept an optional project argument (auto-detected if empty).
Each release ships standalone executables for macOS, Linux, and Windows. You do not need the Rust toolchain — download the binary and run it.
One-line install (macOS / Linux):
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/adrnsyr/mcp-obsidian/releases/latest/download/mcp-obsidian-installer.sh | sh
Windows (PowerShell):
powershell -ExecutionPolicy Bypass -c "irm https://github.com/adrnsyr/mcp-obsidian/releases/latest/download/mcp-obsidian-installer.ps1 | iex"
Manual download: grab the archive for your platform from the
Releases page,
extract it, and put the mcp-obsidian binary somewhere on your PATH.
Prebuilt binaries are the default (lightweight) build — semantic search is not included. If you need
memory_semantic_search, build from source with thesemanticfeature (see below).
cargo build --release
# binary: target/release/mcp-obsidian
Semantic search (memory_semantic_search) is opt-in via the cargo feature
semantic, so the default build stays lightweight & offline:
cargo build --release --features semantic
This build bundles pure-Rust local embeddings (candle). On first use, the
multilingual model paraphrase-multilingual-MiniLM-L12-v2 (~470 MB) is
downloaded once into the HuggingFace cache (~/.cache/huggingface), then runs
offline. A multilingual model was chosen so that non-English memories (e.g.
Indonesian) are still searched correctly by meaning. Without this feature, the
memory_semantic_search tool remains registered but returns a message
explaining how to enable it.
When the
semanticfeature is active,memory_suggest&memory_clusteralso automatically use embeddings (by meaning); without the feature, both fall back to TF-IDF/graph.
The file watcher (the watch feature) monitors the memory folder and
regenerates _MOC.md automatically when memories are edited directly in
Obsidian (outside the MCP tools):
cargo build --release --features watch
It uses notify (FSEvents/inotify) with a 2-second debounce to dampen the burst
of events when an editor saves. Files produced by the server itself (_MOC.md,
dotfiles) are ignored so no loop occurs. The features can be combined:
cargo build --release --features "semantic watch".
claude mcp add obsidian-memory \
--env OBSIDIAN_VAULT_PATH="/path/to/Obsidian Vault" \
-- /path/to/mcp-obsidian/target/release/mcp-obsidian
Or manually in ~/.claude.json / another MCP client's config:
{
"mcpServers": {
"obsidian-memory": {
"command": "/path/to/mcp-obsidian/target/release/mcp-obsidian",
"env": {
"OBSIDIAN_VAULT_PATH": "/path/to/Obsidian Vault"
}
}
}
}
Replace
/path/to/...to match your system. ExampleOBSIDIAN_VAULT_PATHper OS: macOS~/Documents/Obsidian Vault, Linux~/obsidian/vault, WindowsC:\Users\<name>\Documents\Obsidian Vault.
Note: logs are intentionally written to stderr because stdout is used by the MCP protocol (JSON-RPC). Do not write anything to stdout.
cargo test # runs unit + integration tests
The tests cover write/read roundtrips, preservation of the created timestamp
on update, search/list, map generation, smart-relation scoring, wikilink
extraction & backlink graph, resource URI parsing, prompt rendering, and a
concurrency regression test: because memory_write performs a
read-modify-write and then regenerates _MOC.md, all operations are serialized
through a mutex (io_lock) so that no writes race and the map is never read
half-built.
memory_suggest)Beyond manual links (the links field), the server can suggest links
automatically by combining two similarity signals:
|A∩B| / |A∪B|name + description + body.
If the build uses the semantic feature, this uses embeddings (by
meaning); otherwise it falls back to TF-IDF vectors (normalized tokens,
ID/EN stopwords).Final score = 0.6 · tag + 0.4 · content. Memories already present in links
are skipped, results are ranked and cut to top-N above a threshold. Each
suggestion is explainable: it also reports shared_tags & shared_terms.
// Suggestions for all memories in the project (read-only)
{"name": "memory_suggest", "arguments": {"project": "demo"}}
// Suggestions for a single memory + write directly into the links field
{"name": "memory_suggest", "arguments": {"project": "demo", "name": "auth-flow", "apply": true}}
// Tune count & threshold: top 3, minimum score 0.1
{"name": "memory_suggest", "arguments": {"project": "demo", "top": 3, "threshold": 0.1}}
_MOC.md also automatically shows a 💡 Suggested Relations section
(suggestions, not real links until you apply).
memory_cluster)Memories are grouped into themes via Louvain community detection on the
undirected link graph (built from the links field + [[wikilink]] in the
body; edge weights accumulate when there are multiple links between the same
pair). If the build uses the semantic feature, the graph is also enriched with
embedding-similarity edges (pairs with cosine ≥ 0.6) before Louvain — so
themes form from links and semantic proximity, not just explicit links.
Louvain maximizes modularity Q:
Q = Σ_c [ Σ_in(c) / 2m − ( Σ_tot(c) / 2m )² ]
where Σ_in is the weight of a community's internal edges, Σ_tot is the
community's total degree, and m is the total edge weight. The higher Q (max
~1.0), the sharper the community separation. A memory with no links becomes its
own singleton community.
// Group the project's memories into themes (read-only)
{"name": "memory_cluster", "arguments": {"project": "demo"}}
Note:
Q = 0is normal when all linked memories form one connected component with no sub-structure — there is no "community within a community" to split. Q rises as soon as several relatively separate groups appear.
_MOC.md shows a 🧩 Themes section when there is more than one meaningful
cluster.
memory_semantic_search)Requires a
--features semanticbuild (see the Build section).
Unlike memory_search (keyword-matching), semantic search finds memories by
meaning. For example, the query "reasons for choosing a programming language" finds a memory titled "Why we use Rust" even though no words match.
Full design notes (how embeddings work, the multilingual model decision, real-world test results, & technical notes): see semantic.md.
How it works:
name + description + body) is embedded into a 384-dimensional
vector with the multilingual model paraphrase-multilingual-MiniLM-L12-v2
(candle, pure-Rust, local) — supporting 50+ languages including Indonesian.memory/<project>/.embeddings.json.
Only changed memories (detected via a content hash) are re-embedded — so
subsequent searches are fast.{"name": "memory_semantic_search",
"arguments": {"project": "demo", "query": "why this architecture was chosen", "top": 5}}
The .embeddings.json file is a pure cache — safe to delete (it will be rebuilt)
and not treated as a memory.
memory_recall)Requires a
--features semanticbuild (see the Build section).
memory_recall is a single-call context retrieval for AI agents. Instead of
chaining semantic_search → read → backlinks → cluster yourself, a single
call returns an already-enriched context package:
{"name": "memory_recall",
"arguments": {"project": "demo", "query": "why this project uses the Rust language", "top": 3}}
Each result item contains: name, description, score (semantic relevance),
type, tags, body, links, backlinks, theme. Ideal to use directly as
context for an LLM with no extra steps.
Released under the MIT license. Free to use, modify, and redistribute.
MCP server (Rust) for per-project memory in an Obsidian vault — plain Markdown, no database
Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración stdio para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
Este registro no indica ninguna variable de entorno obligatoria.
MCP Obsidian se ejecuta localmente por stdio.
Última comprobación: 2026-10-27. MCP server (Rust) for per-project memory in an Obsidian vault — plain Markdown, no database