Obsidian Vault MCP: Zotero literature in Obsidian
Obsidian Vault MCP
A local MCP server for scientific literature: Zotero as source, MinerU for full text, Obsidian for notes, wiki and analysis
- 95 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The server writes and overwrites notes, wiki pages and files in an Obsidian vault
- Parsing through MinerU may send PDFs to an external service
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/obsidian-vault-mcpDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The server writes and overwrites notes, wiki pages and files in an Obsidian vault
- Parsing through MinerU may send PDFs to an external service
This is third-party code. Review the repository files before installing.
What it does
Obsidian Vault MCP links three programs into one literature workflow: Zotero holds the sources, MinerU turns PDFs into Markdown and an Obsidian vault accumulates notes, wiki pages and analyses. The key of a record is the `zoteroKey` of the Zotero parent item, so every work has a stable identity. The server offers 31 tools in groups: system and configuration, Zotero (search, collections, notes, annotations), import and sync, MinerU, navigation and validation, Analysis, wiki and transactions. BibTeX, stored and linked attachments are supported. For each work it creates a main note, the PDF and full text with its own image folder, plus an index `Literature/index.md` and a `Literature.base` database. On top of the tools sit 7 skills: `paper-qa`, `full-read`, `passage-qa`, `figure-qa`, `compare-papers`, `literature-review` and `concept-learning`. Five analysis types (`full_read`, `literature_review`, `passage_qa`, `figure_qa`, `concept`) are saved in the vault. Every write goes through a dry run, then a transaction with a backup and rollback. `obsidian-vault-mcp agent install codex` installs the server into a client (`claude`, `opencode`, `pi`, `hermes` and `workbuddy` also work).
Who it is for. Researchers and graduate students who keep a Zotero library and Obsidian notes and want to read papers with an agent through a traceable workflow.
Good fit when
- You want to load a Zotero paper into the vault with full text and images
- You need an answer about a specific passage or figure with its place in the text
- You write a review over a set of works and want the result saved as an analysis note
- You want to compare several papers in a matrix
- You want every vault edit to show as a dry run first, with rollback
Not a fit when
- Zotero Desktop with the local API is not running: it is the source
- The vault was never opened in Obsidian: the target folder must contain `.obsidian/`
- You want a simple note from a single file without a Zotero library: the server is built around it
Example request
Import the paper ABCD1234 from Zotero, parse the PDF with MinerU and answer how the authors justify the method, with a link to the paragraph.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
OBSIDIAN_VAULT_PATHrequired- Path to the Obsidian vault that contains a `.obsidian` folder
Limitations
Python 3.10 or later, a running Zotero Desktop with the local API and a vault already opened in Obsidian are required. PDF parsing through MinerU may send files to an external service, so check organization policy and document rights. The author recommends local `stdio` and keeping SSE and HTTP behind trusted authentication. Transaction backups do not replace a full vault backup. The README is in Chinese, with an English version in `README.en.md`. The install is pinned to version 3.0.2.
How to disable. Remove the `obsidian-literature` entry from the MCP configuration and uninstall the package with `uv tool uninstall zotero-obsidian-mcp`. Notes in the vault stay as ordinary Markdown files.
FAQ
How do I install Obsidian Vault MCP?
With `uv tool install "zotero-obsidian-mcp==3.0.2"`, then `obsidian-vault-mcp config init --vault-path <path>`. Alternatives are `pipx`, `pip` and the registry entry `io.github.luffysolution-svg/obsidian-vault-mcp`.
Which clients does it work with?
Codex, Claude Code, OpenCode, Pi, Hermes and WorkBuddy. Codex and Claude Code get a marketplace plugin, MCP and 7 skills, OpenCode gets MCP and skills, and Hermes and WorkBuddy get only the MCP setup.
What does MinerU do in this chain?
It turns a PDF into Markdown, with a separate image folder and relative links per work. The file appears at a path like `Literature/attachment/MinerU/ABCD1234.md`.
Is writing to the vault safe?
Every write first runs as a dry run, then is recorded as a transaction with a `transactionId`, a backup, a lock, an atomic replace and rollback. This does not replace a separate vault backup.
Is Zotero required?
Yes, Zotero Desktop with the local API enabled. It is the source and provides the primary record key `zoteroKey`.
Discussion
No questions or reviews yet.
Related
MCP serversA Zotero plugin with a built-in MCP server: the agent searches the library, reads PDFs and notes, and works with annotations and metadata
A local MCP server for arXiv literature work: section-level paper reads, BibTeX from metadata, topic watches
A local MCP server lets an agent search your Zotero library, Obsidian vault and Apple Notes through a C++ search core
A CLI and MCP server for a research paper library: the agent searches, imports and reads papers and keeps Markdown notes in your vault
A Zotero MCP server: keyword and semantic search, PDF passages with page numbers, CSL citations and adding papers by DOI
The MCP server of the seerai Zotero plugin gives outside agents 46 tools: library and scholarly search, reviews and a workspace.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Obsidian Vault MCP: Zotero literature in Obsidian (this card) | no | not required | 95 | |
| Zotero MCP | no | key is optional | 5,884 | Zotero access without an Obsidian vault or MinerU full text |
| obsidian-second-brain | no | 5,297 | general Obsidian memory, not tied to Zotero |
README in short
The README shows the architecture as a diagram from a natural-language task through skills and tools to the Zotero, PDF, MinerU and Obsidian chain. It then lists key features, installation through uv, pipx and the MCP registry, first-time setup, installing into agents, a skills table, the 31-tool breakdown and security boundaries.