Stratosphere MCP Zotero

Connect your Zotero library to an AI assistant. Ask questions, find papers, save sources, fix metadata — in plain language.

Works with Claude, Gemini CLI, OpenAI Codex, and any other MCP client.

What you can ask

You ask in plain language. The assistant picks the right tool. You stay in your normal chat.

Find a paper

"Find papers about deception in the Deception Research group." "Do I have anything by Kahneman in my ML collection?" "Do I already have this DOI?" "Find the paper with BibTeX key smith2023."

The assistant searches your library and returns a short list with title, authors, year, and DOI.

Search several libraries at once

"Do I have anything about bananas in Exotic Research or my personal library?"

You get one answer with results from both.

Browse by tag or collection

"Show me everything tagged 'to-read'." "What's in my Reading Queue collection?" "List all papers tagged 'important' in the Deception Research group."

The assistant lists the items. Tags must match exactly.

Look up one item

"Show me the full details for item ABCD1234." "Where is the PDF for this paper on my disk?"

You get normalised metadata, or a local PDF path you can open in your editor.

Count your library

"How many papers do I have in my personal Zotero?" "How big is the Deception Research group library?"

You get a number. By default it counts top-level items only, not PDFs and notes.

Save and update

"Save this paper to my Reading Queue collection." "Fix the DOI on item ABCD1234 and add the tag 'to-read'."

The assistant adds or updates the item and shows you what changed. Only the fields you mention are touched — nothing else is overwritten.

---

A few things to know

• Group libraries: All tools accept a library argument — "personal", a group name like "Deception Research", or a numeric group ID. Group names are fuzzy-matched.
• Collections by name: Pass a collection name and the tool resolves it. If two collections have similar names, the tool asks you to pick.
• Save/update format: Separate authors with ; and tags with ,.

  creators="Ada Lovelace; Grace Hopper"
  creators="author: Turing, Alan; editor: Knuth, Donald"
  tags="reading-queue, llm, bibliography"
  

• Pagination: Tools that list items (find_library_sources, find_by_tag) cap at 100 results per call. Use the offset argument to page through larger sets — total_results in the response tells you when to stop.
• BibTeX keys: Looking up a paper by its citation key requires the Better BibTeX Zotero plugin, which writes the key into the item's extra field.

Prerequisites

Zotero API key:

1. Go to your Zotero account settings → API Keys
2. Create a key with the library permissions you need (personal and/or group access)
3. Copy it into your .env file

The server automatically resolves your user ID and all accessible group libraries from the API key — no manual library IDs required.

Quick start (Docker)

# Build
docker compose build

# Configure
cp .env.example .env
# Fill in ZOTERO_API_KEY, then lock down the file:
chmod 600 .env

Register with your AI assistant:

<details> <summary><strong>Claude</strong></summary>

Claude Desktop — edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/.env",
        "zotero-mcp:latest",
        "serve"
      ]
    }
  }
}

Use the full path to your .env file. Claude Desktop launches Docker from an unknown working directory, so relative paths won't work.

Claude Code:

claude mcp add --transport stdio zotero -- \
  docker run --rm -i \
    --env-file /absolute/path/to/.env \
    zotero-mcp:latest serve

</details>

<details> <summary><strong>Gemini CLI</strong></summary>

Edit ~/.gemini/settings.json (or .gemini/settings.json in your project root):

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "--env-file", "/absolute/path/to/.env",
        "zotero-mcp:latest",
        "serve"
      ]
    }
  }
}

</details>

<details> <summary><strong>OpenAI Codex</strong></summary>

Edit ~/.codex/config.toml (or .codex/config.toml in your project root):

[[mcp_servers]]
name = "zotero"
command = "docker"
args = [
  "run", "--rm", "-i",
  "--env-file", "/absolute/path/to/.env",
  "zotero-mcp:latest",
  "serve"
]

</details>