# Zoteus

> ⚡ The everything Zotero MCP server — complete Zotero Web API v3 + desktop local API for Claude & any MCP client. Search, safe writes, add-by-DOI, CSL citations, hybrid semantic search, and a scholarly-context graph. TypeScript, local-first.

- **Type:** MCP server
- **Install:** `agentstack add mcp-oscardvs-zoteus`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [oscardvs](https://agentstack.voostack.com/s/oscardvs)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [oscardvs](https://github.com/oscardvs)
- **Source:** https://github.com/oscardvs/zoteus
- **Website:** https://zoteus.com/

## Install

```sh
agentstack add mcp-oscardvs-zoteus
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# ⚡ Zoteus

### Your Zotero library, inside every AI conversation — with real citations, not hallucinations.

The **everything Zotero MCP server**. Give Claude, Cursor, and any [MCP](https://modelcontextprotocol.io) client complete, **safe** access to your [Zotero](https://www.zotero.org) library — search papers, add by DOI, format bibliographies in ~2,800 styles, run semantic search over your own PDFs, and ground every answer in a source you actually own. **Local-first. Private. One command.**

[](https://www.npmjs.com/package/@oscardvs/zoteus)
[](https://www.npmjs.com/package/@oscardvs/zoteus)
[](./LICENSE)
[](https://modelcontextprotocol.io)
[](https://registry.modelcontextprotocol.io)

[](https://zoteus.com)

```bash
npx -y @oscardvs/zoteus
```

---

## Install in 30 seconds

| Client | Command |
|---|---|
| **Claude Code** | `claude mcp add --transport stdio zoteus -- npx -y @oscardvs/zoteus` |
| **Cursor / VS Code / Claude Desktop / Codex / Zed…** | `npx add-mcp @oscardvs/zoteus` |
| **Claude Desktop (one-click)** | download `zoteus.mcpb` from the [latest release](https://github.com/oscardvs/zoteus/releases/latest) → double-click |
| **claude.ai (web)** | Add custom connector → your hosted URL (OAuth) |

Add your cloud key for writes/sync/groups (optional — reads work key-free against the desktop app):

```bash
claude mcp add --transport stdio zoteus -e ZOTERO_API_KEY=xxxxx -- npx -y @oscardvs/zoteus
```

> Get a key at [zotero.org/settings/keys](https://www.zotero.org/settings/keys). For key-free local reads, enable **Settings → Advanced → "Allow other applications on this computer to communicate with Zotero"** in the desktop app.

---

## Why Zoteus?

There are several Zotero MCP servers now. Zoteus is the one that does **everything** — and adds the parts everyone else skips. The difference that matters: **Zoteus treats your library as the source of truth, not a search index.** When you ask Claude to "draft a methods paragraph citing the five most relevant papers in my collection," it runs that against *your verified, already-curated references* — no invented citations, no Python stack, nothing leaves your machine.

| | **Zoteus** | Other Zotero MCP servers | Web AI (Elicit/SciSpace) |
|---|:---:|:---:|:---:|
| Operates on **your own** library | ✅ | ✅ (varies) | ❌ (web-wide) |
| Complete Web API v3 **+** desktop local API | ✅ | partial | n/a |
| **Safe** transactional writes (reversible, gated) | ✅ | rare | ❌ |
| CSL bibliographies (~2,800 styles) | ✅ | rare | ❌ |
| Local hybrid semantic search over PDFs | ✅ | some (cloud) | varies |
| No Python — TypeScript, one `npx` | ✅ | varies | n/a |
| MCP Resources + Prompts + code-execution | ✅ | ❌ | n/a |
| Local-first / private · Open-source (MIT) | ✅ | varies | ❌ |

## What you can do

- **Find anything in your own work.** *"Find papers in my library that argue against X"* — hybrid keyword + semantic search across metadata, full text, and annotations, returned **with the page number**.
- **Cite without hallucinating.** Zoteus surfaces *your* Zotero citation data and formats it with [citeproc-js](https://citeproc-js.readthedocs.io) in any [CSL](https://citationstyles.org) style — it never invents a reference.
- **Add a paper by identifier.** Drop in a DOI/ISBN/PMID/arXiv id and Zoteus fetches the metadata and files it — no account needed for the import → format path.
- **Write back, safely.** Create items, edit, tag, organize — versioned with optimistic-locking retries, reversible trash by default, permanent delete opt-in and confirmation-gated.
- **Ground claims in the PDF.** `zotero_get_fulltext` returns the relevant passage with character offsets, nearest heading, and a page locator.
- **Follow the scholarship.** A scholarly-context graph over OpenAlex / Crossref / Semantic Scholar.
- **Built for agents.** ~28 consolidated, well-described tools (not 70 thin endpoint mirrors), `zotero_*`-namespaced, structured outputs, and a generated tool tree for the [code-execution-with-MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) pattern.

## How it works

1. **Install** — one `npx` command (or the one-click `.mcpb`).
2. **Connect** — paste your Zotero API key (or just run the desktop app for key-free local reads).
3. **Ask** — your AI can now search, cite, add, and organize your library.

Zoteus auto-detects your running Zotero desktop app and uses its fast, key-free **local API** for reads (full PDFs, real saved-search results), falling back to the cloud **Web API v3** for writes, sync, and group libraries.

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `ZOTERO_API_KEY` | — | Cloud auth (writes/sync/groups; optional for local-only reads) |
| `ZOTEUS_LOCAL` | `auto` | `auto\|on\|off` — use the Zotero desktop local API |
| `ZOTEUS_EMBEDDINGS` | `local` | `local\|openai\|gemini\|off` for semantic search |
| `ZOTEUS_ALLOW_DELETE` | `false` | Must be `true` to expose permanent deletion |

Full table in [`docs/configuration.md`](./docs/configuration.md). Running a shared/remote instance? See [`docs/remote-oauth.md`](./docs/remote-oauth.md) (self-host the OAuth remote on loopback or behind your own proxy).

## Documentation

📚 **[zoteus.com/docs](https://zoteus.com/docs)** · [Architecture](./docs/architecture.md) · [Safe writes](./docs/writing.md) · [Citations](./docs/citations.md) · [Semantic search](./docs/semantic-search.md) · [Scholarly context](./docs/scholar.md) · [Code execution](./docs/code-execution.md)

## Contributing

Contributions welcome — see [`CONTRIBUTING.md`](./CONTRIBUTING.md). MIT licensed.

## Acknowledgements

Built on the [Model Context Protocol](https://modelcontextprotocol.io), the [Zotero Web API](https://www.zotero.org/support/dev/web_api/v3/basics), [citeproc-js](https://citeproc-js.readthedocs.io), and the [Citation Style Language](https://citationstyles.org). Not affiliated with or endorsed by the Corporation for Digital Scholarship / Zotero.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [oscardvs](https://github.com/oscardvs)
- **Source:** [oscardvs/zoteus](https://github.com/oscardvs/zoteus)
- **License:** MIT
- **Homepage:** https://zoteus.com/

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-oscardvs-zoteus
- Seller: https://agentstack.voostack.com/s/oscardvs
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.