# Zotero MCP

Connect an AI agent to a Zotero library to search papers, read PDFs, add records, and work with annotations. Useful when research questions depend on your own collection.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5548
- Author: 54yyyu
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/54yyyu/zotero-mcp
- Updated: 2026-10-16
- HTML: https://affpapa.org/en/nevibecode/mcp/zotero-mcp

## What it does

The server searches by title, author, tag, collection, and full text, with semantic search also available. It reads metadata, BibTeX, and PDF page ranges; page images can help when text extraction garbles equations or tables. An agent can add papers by DOI, URL, ISBN, BibTeX, or file, manage collections and tags, and merge duplicates.

In local mode, reads come from `zotero.sqlite`. Writing requires a running Zotero 10+ instance with local access enabled; older versions use the web API with `ZOTERO_API_KEY` and `ZOTERO_LIBRARY_ID`. Python 3.10+ is required for installation. Without local API permission, writes to Zotero 10+ will not work.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `ZOTERO_LOCAL`, `ZOTERO_API_KEY`, `ZOTERO_LIBRARY_ID`, `ZOTERO_LIBRARY_TYPE`, `ZOTERO_MCP_TOOLSETS` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env ZOTERO_LOCAL=<ZOTERO_LOCAL> --env ZOTERO_API_KEY=<ZOTERO_API_KEY> --env ZOTERO_LIBRARY_ID=<ZOTERO_LIBRARY_ID> --env ZOTERO_LIBRARY_TYPE=<ZOTERO_LIBRARY_TYPE> --env ZOTERO_MCP_TOOLSETS=<ZOTERO_MCP_TOOLSETS> --transport stdio zotero-mcp -- uvx zotero-mcp-server
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zotero-mcp-server <command>

### Codex

**Platform CLI**
```bash
codex mcp add zotero-mcp --env ZOTERO_LOCAL=<ZOTERO_LOCAL> --env ZOTERO_API_KEY=<ZOTERO_API_KEY> --env ZOTERO_LIBRARY_ID=<ZOTERO_LIBRARY_ID> --env ZOTERO_LIBRARY_TYPE=<ZOTERO_LIBRARY_TYPE> --env ZOTERO_MCP_TOOLSETS=<ZOTERO_MCP_TOOLSETS> -- uvx zotero-mcp-server
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zotero-mcp-server <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "zotero-mcp": {
            "command": "uvx",
            "args": [
                "zotero-mcp-server"
            ],
            "env": {
                "ZOTERO_LOCAL": "<ZOTERO_LOCAL>",
                "ZOTERO_API_KEY": "<ZOTERO_API_KEY>",
                "ZOTERO_LIBRARY_ID": "<ZOTERO_LIBRARY_ID>",
                "ZOTERO_LIBRARY_TYPE": "<ZOTERO_LIBRARY_TYPE>",
                "ZOTERO_MCP_TOOLSETS": "<ZOTERO_MCP_TOOLSETS>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zotero-mcp-server <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "zotero-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "zotero-mcp-server"
            ],
            "env": {
                "ZOTERO_LOCAL": "<ZOTERO_LOCAL>",
                "ZOTERO_API_KEY": "<ZOTERO_API_KEY>",
                "ZOTERO_LIBRARY_ID": "<ZOTERO_LIBRARY_ID>",
                "ZOTERO_LIBRARY_TYPE": "<ZOTERO_LIBRARY_TYPE>",
                "ZOTERO_MCP_TOOLSETS": "<ZOTERO_MCP_TOOLSETS>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zotero-mcp-server <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e ZOTERO_LOCAL=<ZOTERO_LOCAL> -e ZOTERO_API_KEY=<ZOTERO_API_KEY> -e ZOTERO_LIBRARY_ID=<ZOTERO_LIBRARY_ID> -e ZOTERO_LIBRARY_TYPE=<ZOTERO_LIBRARY_TYPE> -e ZOTERO_MCP_TOOLSETS=<ZOTERO_MCP_TOOLSETS> zotero-mcp uvx zotero-mcp-server
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from zotero-mcp-server <command>

## When to use it
- search a Zotero library for papers on a topic
- read PDF text and selected pages
- retrieve BibTeX for a paper
- add a paper to the library by DOI
- find and merge duplicate records

## Example prompts
- Find papers about transformer architectures in my library.
- Read this record’s PDF and explain the equation on the page I mention.
- Add a paper to Zotero by DOI and place it in a suitable collection.

## Similar
- [Zotero](https://affpapa.org/en/nevibecode/skills/zotero.md) — skill · 24 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md