DocsAgent MCP
A local MCP server lets an agent search your Zotero library, Obsidian vault and Apple Notes through a C++ search core
- 578 ★ on the repository
- Last commit
Extended access
Why this level
- The agent reads your personal library, notes and annotations in full, including material unrelated to your question
- By default the core listens on 0.0.0.0 port 23120, meaning every network interface: narrow `coreHost` to a local address
- With the write tools enabled the agent adds notes and tags and changes collections in Zotero, up to 200 items per call
Install
- Works in
Manual install
npx @docsagent/docsagent startStarts the search core for your platform. Check its state with npx @docsagent/docsagent status.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent reads your personal library, notes and annotations in full, including material unrelated to your question
- By default the core listens on 0.0.0.0 port 23120, meaning every network interface: narrow `coreHost` to a local address
- With the write tools enabled the agent adds notes and tags and changes collections in Zotero, up to 200 items per call
This is third-party code. Review the repository files before installing.
What it does
DocsAgent connects a personal knowledge base to an MCP client. An agent searches Zotero articles and PDFs, Obsidian vault notes and, on macOS, Apple Notes. In mixed mode the server merges the results of the three sources into one list. Search runs in a resident C++ core that builds a BM25 index and ranks text passages. By the author's benchmark, search over a library of 1,506 PDFs takes about 15 milliseconds and the index builds in 141 seconds. There are eight tools. Five read data: `list_sources`, `search`, `get_content`, `get_metadata` and `list_library`. Three write to Zotero: `import_item`, `add_note` and `batch_modify`.
Who it is for. For researchers and students with a Zotero library, and for anyone who keeps notes in Obsidian or Apple Notes and wants to search them from Claude Desktop, Cursor or Cline.
Good fit when
- You need to find passages on a topic across hundreds of Zotero PDFs and get them with a link to the library entry
- You need a source list: metadata, annotations and a citation in BibTeX or CSL JSON
- You need an exact-fragment search: `grep` mode looks for a literal string without tokenization
- You want to add a note to a Zotero item or import an article by DOI, ISBN or arXiv ID
Not a fit when
- You need a web search: the server searches only personal sources on your computer
- Your material sits in a reference manager or cloud notes other than Zotero, Obsidian and Apple Notes
- The system runs on Linux ARM: the core ships for macOS, Windows x64 and Linux x64
- You need to edit Obsidian or Apple Notes: those sources are read-only
Example request
Find passages in my Zotero library about search quality evaluation methods and show BibTeX citations for the three best-matching papers.MCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
DOCSAGENT_CONFIG- Path to the shared configuration file, ~/.docsagent/config.json by default.
DOCSAGENT_OBSIDIAN_VAULT- Path to the Obsidian vault if it is not in Documents/Obsidian Vault.
DOCSAGENT_APPLE_NOTES_DB- Path to an Apple Notes store instead of the system one.
Limitations
Before work you start the core separately with `npx @docsagent/docsagent start`. The MCP shell does not launch it and exits at once with a hint if it is missing. Apple Notes is available on macOS only. The program looks for the Obsidian vault in Documents/Obsidian Vault, and the `DOCSAGENT_OBSIDIAN_VAULT` variable sets another path. The SKILL.md file in the repository root belongs to a different mode: it describes the `docsagent add` and `docsagent search` commands for PDF, PPTX and DOCX. The Python package installs only from source for now, with `pip install ./python`.
How to disable. Remove the `docsagent` block from mcpServers in the client settings and stop the core with `npx @docsagent/docsagent stop`. The configuration lives in `~/.docsagent/config.json`, and your Zotero and Obsidian data stays untouched.
FAQ
How do I connect DocsAgent to Cursor or Claude Desktop?
Add a `docsagent` block to mcpServers with the command `npx` and the arguments `-y @docsagent/docsagent`. The same block works for Cline and Qwen Code.
Does DocsAgent send my notes and PDFs to the cloud?
No. The core reads Zotero, the Obsidian vault and the Apple Notes store on your computer and builds indexes there. The server goes online only if you list Zotero group libraries in `zoteroGroups`: it syncs those with zotero.org.
What do I set so the agent can write to Zotero?
Set `enableWrites` to `true` in `~/.docsagent/config.json`, and the server registers the write tools. A call with `confirmed` set to `false` returns a preview. Confirmed writes are capped at 30 per hour by default.
How is mixed search different from regular search?
Regular `search` goes through the source in `defaultSource`, Zotero by default. Mixed search ranks each source separately and merges the lists with reciprocal rank fusion at k=60. The reason is that BM25 scores from different sources are not comparable.
Can I run DocsAgent as a remote server with a key?
Yes. Set `transport` to `streamable-http`, the address in `httpListenAddr` (`0.0.0.0:8080` by default) and `authMode` to `api-key` or `oauth2` with token introspection. Origin checks through `allowedOrigins`, roles in `rbacRoles` and a `/health` probe are also available.
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 CLI and MCP server for a research paper library: the agent searches, imports and reads papers and keeps Markdown notes in your vault
The MCP server lets agents read and search local Molio vaults, browse file trees and ask questions about their contents.
A local document base for your agent: hybrid semantic and keyword search plus a web UI for browsing and uploads
A local MCP server for arXiv literature work: section-level paper reads, BibTeX from metadata, topic watches
A self-hosted RAG platform: cited answers over GitHub, Notion, Drive and files, with an MCP mode for Claude Code.
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| DocsAgent (this card) | no | not required | 578 | |
| Zotero MCP | no | not required | 1,264 | connects a Zotero library only, with no Obsidian or Apple Notes |
| Obsidian MCP | no | not required | 748 | reads and edits Markdown files in explicitly configured Obsidian vault folders |
README in short
The project page is built around a three-layer diagram: the MCP shell, JSON-RPC exchange and a resident C++ core. Tables list tool parameters, performance benchmarks and configuration keys.