DocsAgent — Zotero, Obsidian & Apple Notes MCP Server

DocsAgent MCP — Zotero MCP Server 📚⚡

DocsAgent gives AI agents instant, private access to your personal knowledge base. @docsagent/mcp-zotero is the spec-driven MCP (Model Context Protocol) server (Zotero is the first supported source) that lets any AI agent — Claude Desktop, Cursor, Cline, Qwen Code, or any MCP client — search, read, and write your Zotero library through a resident C++ search engine. BM25 full-text search + query-ranked passage retrieval over 1,000+ PDFs at ~15 ms, fully local (RAG-ready knowledge base).

machine. Your PDFs never leave it.

• 🔒 Local-first & private — the engine reads your Zotero library directly on your

low memory footprint (160–227 MB for a 1,500-paper library).

• ⚡ Native C++ search core — inverted-index BM25 + passage ranking, millisecond lookup,

result dedup, and a three-layer write safety gate.

• 🧩 8 MCP tools — 5 read + 3 write, with JSON-schema validated arguments, token budgets,

(origin checks, API-key / OAuth 2.0 token introspection, per-request RBAC, /health probe).

• 🌐 Two transports — stdio for local MCP clients, Streamable HTTP for remote deployment

Python wrapper ship the same tools over the same JSON-RPC contract.

• 🐍 Two shells, one core — this TypeScript package and a feature-equal

Architecture

MCP Client (Claude Desktop / Cursor / Cline / Qwen Code / any MCP host)
        │  stdio (local)   or   Streamable HTTP  /mcp  (remote)
        ▼
MCP shell  ← this package (@docsagent/mcp-zotero / docsagent-mcp-zotero)
   · tool schemas (spec-driven), argument validation, token budget, dedup
   · write orchestration via the Zotero local API, write safety gate, RBAC
   · group-library sync via the Zotero Web API
        │  JSON-RPC 2.0 over HTTP ({coreHost}:{httpPort}/rpc, cpp-httplib)
        ▼
DocsAgent Core (resident C++ engine, papersgpt-agent)
   · reads ~/Zotero/zotero.sqlite + storage/ directly on your machine
   · builds & serves the full-text index (BM25 + passage ranking)

The shell never spawns the core during tool calls and never touches your Zotero files. The core runs as a background service and stays available across MCP client restarts. Tool schemas and error codes: spec/.

Quick Start

1. Start the core

npx @docsagent/mcp-zotero start           # spawn the bundled core for your platform
npx @docsagent/mcp-zotero status          # pid / endpoint / version

Python shell (same verbs, under the core subcommand):

pip install ./python                      # build the wheel locally (PyPI upload pending)
docsagent-mcp-zotero core start

(core stop / core restart also available. The core reads your Zotero data directory, builds the full-text index, and serves JSON-RPC on http://0.0.0.0:23120/rpc.)

2. Configure your MCP client

Claude Desktop / Cursor / Cline / Qwen Code (mcpServers):

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "npx",
      "args": ["-y", "@docsagent/mcp-zotero"]
    }
  }
}

Python shell (same tools, same contract, installed from this repo) — mcpServers:

{
  "mcpServers": {
    "docsagent-zotero-py": {
      "command": "docsagent-mcp-zotero"
    }
  }
}

Install the Python package first (step 1) so docsagent-mcp-zotero is on your PATH.

On startup the shell connects to the core, loads sources, and checks index status. If the core is not running it fails fast with startup instructions — it never spawns anything.

MCP Tools (external API)

8 tools, 5 read + 3 write. Schemas are the single-sourced contract in spec/tools/*.json (mirrored into both packages); arguments are validated before handlers run and failures map to typed docsagent error codes.

list_sources

Every searchable source with capabilities, supported targets/includes/browse modes, filters, and document counts. Call this first.

Shortened. The full README is on GitHub.