zotero-mcp

zotero-mcp connects AI agents such as Claude, Cursor, VS Code, ChatGPT, and Codex to your Zotero library through the Model Context Protocol (MCP). Once it is set up, you can ask an agent to:

• search your library and read item details, abstracts, and formatted references;

• list collections and page through their items;

• create, edit, tag, or delete items through the Zotero Web API v3;

• upload PDFs and other files as attachments;

• turn citation markers in a Word document into real Zotero citations that the Zotero Word plugin can refresh and restyle.

You set it up once: install one command, store your Zotero user ID and API key once, and point every agent at that command.

Contents

• How it works

• Before you start

• Step 1: Set up Zotero

• Step 2: Store your user ID and API key

• Step 3: Install zotero-mcp

• Step 4: Connect your agents

• Step 5: Check that it works

• Use the tools

• Create Word citations

• Update, pin, or remove

• Troubleshooting

• Security

• Contributing

Related MCP server: zotero-mcp

How it works

flowchart LR
    agent["AI agent"] -- "MCP over standard input and output" --> server["zotero-mcp"]
    server -- "reads" --> desktop["Zotero desktop app (local API)"]
    server -- "reads when the app is closed, and every write" --> web["api.zotero.org"]
    web -- "Zotero sync" --> desktop

• Each agent starts zotero-mcp by itself whenever it needs it and talks to it over standard input and output. You never run the server by hand, and it opens no network port.

• Reads go to the Zotero desktop app first, at http://127.0.0.1:23119/api. That is fast and works offline. If the app is closed, or its library has no items yet, reads use https://api.zotero.org instead. Writes always go to api.zotero.org, and Zotero syncs them back to the desktop app.

• The server needs two values from you: your numeric Zotero user ID and a Zotero API key. You store them once, as environment variables, in Step 2.

Before you start

Running commands. Several steps use a terminal:

• Windows: open PowerShell: press Start, type PowerShell, and press Enter.

• macOS: open Terminal from Applications → Utilities.

• Linux: open your terminal app.

Copy one code block at a time, paste it into the terminal, and press Enter. Text that starts with YOUR_, such as YOUR_USER_ID, is a placeholder: replace all of it with your own value. Example paths that contain you, such as C:\Users\you\..., stand for paths on your computer; Step 3 prints yours.

Step 1: Set up Zotero

1. Install Zotero. Download it from zotero.org/download, install it, and open it.

2. Sign in and sync. Open Zotero's settings (Edit → Settings on Windows and Linux, Zotero → Settings on macOS), choose Sync, sign in with your zotero.org account, and let the library sync. If you have no account yet, create one at zotero.org/user/register.

3. Turn on the local API. In the same settings window, choose Advanced and select Allow other applications on this computer to communicate with Zotero. The server then reads your library from the desktop app, quickly and without the internet.

4. Create an API key. Sign in at zotero.org and open Create a new private key.

   • Enter a name you will recognize, such as zotero-mcp.

   • Under Personal Library, allow library access. Allow write access only if agents should be able to create, edit, upload, or delete items.

   • Save the key and copy it right away. Zotero shows it only once.

5. Copy your user ID. The API keys page shows your user ID for API calls. It is a number, not your username.

6. Optional: install the Word plugin. For Word citations, open Zotero's settings, choose Cite → Word Processor Plugins, and install the Microsoft Word add-in. Restart Word; a Zotero tab appears. Installing the word processor plugin has more detail.

Treat the API key like a password: it opens your library. Never paste it into a chat, an issue, a screenshot, or a file you share.

Step 2: Store your user ID and API key

The server reads two environment variables:

Store them once for your user account, and every agent can find them. On Windows, the key never has to be pasted into an agent's settings. On macOS and Linux, a few apps need the values in their own config; Step 4 says which. The server does not read .env files; .env.example only lists the names.

Windows

1. Open PowerShell.

2. Save your user ID. Replace YOUR_USER_ID with the number, and keep the quotation marks:

   [Environment]::SetEnvironmentVariable("ZOTERO_USER_ID", "YOUR_USER_ID", "User")

3. Save your API key. This command asks for the key and hides it while you paste, so the key never appears on screen or in PowerShell's history. It is one long line; copy all of it:

   $key = Read-Host "Paste your Zotero API key" -AsSecureString; [Environment]::SetEnvironmentVariable("ZOTERO_API_KEY", [System.Net.NetworkCredential]::new("", $key).Password, "User"); Remove-Variable key

4. Check both values. The first line prints your user ID; the second prints True:

   [Environment]::GetEnvironmentVariable("ZOTERO_USER_ID", "User")
   [bool][Environment]::GetEnvironmentVariable("ZOTERO_API_KEY", "User")

Prefer a window to commands? Press Start, type environment variables, open Edit environment variables for your account, and add both variables under User variables.

On Windows, the server also reads these two variables directly from Windows whenever an agent does not pass them. They therefore work in every agent at once, including Claude Desktop and apps installed from the Microsoft Store, without restarting anything.

macOS and Linux

Run steps 2 to 5 in the same terminal window.

1. Open a terminal.

2. Tell the next commands which startup file your shell reads. macOS uses zsh by default:

   RC=~/.zshrc

   Most Linux systems use bash:

   RC=~/.bashrc

   echo $SHELL shows your shell. If you use bash on macOS, run RC=~/.bash_profile instead.

3. Save your user ID. Replace YOUR_USER_ID with the number:

   echo 'export ZOTERO_USER_ID="YOUR_USER_ID"' >> "$RC"

4. Save your API key. This command asks for the key without showing it, so the key never appears on screen or in your shell history. It is one long line; copy all of it:

   printf "Paste your Zotero API key: "; read -rs key; echo; echo "export ZOTERO_API_KEY=\"$key\"" >> "$RC"; unset key

5. Load the new values and check them. The second line prints your user ID; the third prints API key is set:

   source "$RC"
   echo "$ZOTERO_USER_ID"
   [ -n "$ZOTERO_API_KEY" ] && echo "API key is set"

Agents started from a new terminal see these values. Apps opened from the Dock or an application menu usually do not read your shell's startup file; Step 4 shows what to do for those agents.

Step 3: Install zotero-mcp

Install Git

uv downloads zotero-mcp from GitHub with Git. Check whether Git is installed:

git --version

If that prints a version number, continue with Install uv. Otherwise, install Git:

Close the terminal, open a new one, and run git --version again.

Install uv

uv installs Python programs in their own environments, and downloads Python itself if needed. Check whether it is installed:

uv --version

If that does not print a version number, install uv.

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Close the terminal, open a new one, and run uv --version again. The uv installation guide lists other ways to install it, such as WinGet and Homebrew.

Install the server

uv tool install git+https://github.com/Jayaram-Nambiar/zotero-mcp.git

The output includes Installed 1 executable: zotero-mcp. uv may then warn that its bin folder is not on your PATH; that is fine, because agents use the full path from the next step. Run uv tool update-shell only if you also want to type zotero-mcp in a terminal.

Check the installed version:

uv tool list

It lists zotero-mcp v1.0.2 or newer.

Copy the full path of the command

Agents start the server by its full path. Print it.

Windows (PowerShell):

Join-Path (uv tool dir --bin) "zotero-mcp.exe"

This prints a path such as C:\Users\you\.local\bin\zotero-mcp.exe.

macOS and Linux:

echo "$(uv tool dir --bin)/zotero-mcp"

This prints a path such as /Users/you/.local/bin/zotero-mcp. Keep the path at hand for Step 4.

Step 4: Connect your agents

Add the server to every agent you use, always under the name zotero. Set up only the agents you have; skip the rest.

Paths in config files

The examples write the command as /path/to/zotero-mcp. Replace it with the full path from Step 3, written for the kind of file you are editing:

On Linux, the path usually starts with /home/you/ instead of /Users/you/.

Edit a JSON config file safely

Most agents keep their servers in a JSON file, in a block named mcpServers; VS Code names the block servers, and opencode names it mcp. Each agent's section below gives the commands to open and to check its file. When you add zotero:

1. The file is empty or new: paste the agent's whole example.

2. The file has other settings but no server block: keep everything that is already there. Put a comma after the last setting, then paste the server block inside the outer braces:

   {
     "preferences": {
       "example-setting": true
     },
     "mcpServers": {
       "zotero": {
         "command": "/path/to/zotero-mcp"
       }
     }
   }

3. The file already has a server block: add only the "zotero": { ... } entry inside it, with a comma after the entry before it:

   {
     "mcpServers": {
       "other-server": {
         "command": "other-command"
       },
       "zotero": {
         "command": "/path/to/zotero-mcp"
       }
     }
   }

Paste the examples rather than typing them: some editors turn straight quotation marks into curly ones, which breaks JSON. After saving, run the agent's check command. If it reports an error, a comma, quotation mark, or brace is missing. If it says it cannot find the file, the path in the command is wrong, not the JSON.

Claude Desktop

Claude Desktop, the Claude chat app, reads this file:

Claude can also show you the file: open its Settings from the Claude menu, choose Developer, and click Edit Config. Claude creates the file if it does not exist yet. Then quit Claude before you edit it.

1. Quit Claude Desktop.

   • Windows: right-click the Claude icon in the notification area at the right end of the taskbar (click ^ if the icon is hidden) and choose Quit.

   • macOS: choose Claude → Quit Claude in the menu bar, or press ⌘Q.

2. Open the file.

   Windows (PowerShell). If Notepad asks whether to create the file, choose Yes:

   notepad "$env:APPDATA\Claude\claude_desktop_config.json"

   macOS (Terminal):

   mkdir -p "$HOME/Library/Application Support/Claude"
   touch "$HOME/Library/Application Support/Claude/claude_desktop_config.json"
   open -e "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

3. Add the server, following Edit a JSON config file safely.

   Windows. Claude Desktop does not pass your variables to servers, but on Windows the server reads them from Windows itself, so the entry needs only the command:

   {
     "mcpServers": {
       "zotero": {
         "command": "C:\\Users\\you\\.local\\bin\\zotero-mcp.exe"
       }
     }
   }

   macOS. The entry has to carry your two values, because Claude Desktop does not pass your variables to servers. Keep this file private:

   {
     "mcpServers": {
       "zotero": {
         "command": "/Users/you/.local/bin/zotero-mcp",
         "env": {
           "ZOTERO_USER_ID": "YOUR_USER_ID",
           "ZOTERO_API_KEY": "YOUR_API_KEY"
         }
       }
     }
   }

4. Save the file and check it.

   Windows (PowerShell):

   Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" -Raw | ConvertFrom-Json

   macOS (Terminal):

   python3 -m json.tool "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

5. Close the editor and start Claude Desktop again.

6. Check the connection: in a chat, click + (Add files, connectors, and more) at the bottom left of the message box, point to Connectors, choose Manage connectors, and select zotero to see its tools.

Claude Code

Claude Code keeps its servers in its own settings, shared by the terminal, the Code tab of the Claude desktop app, and the IDE extensions.

1. Open a terminal.

2. Add the server for all your projects, with the full path from Step 3:

   claude mcp add --scope user --transport stdio zotero -- "/path/to/zotero-mcp"

   On Windows, for example:

   claude mcp add --scope user --transport stdio zotero -- "C:\Users\you\.local\bin\zotero-mcp.exe"

3. Check the connection: claude mcp get zotero shows Status: ✔ Connected. Inside a Claude Code session, /mcp lists the connected servers.

Claude Code passes its environment to the server, so the entry needs no env block.

Cursor

Cursor reads ~/.cursor/mcp.json (%USERPROFILE%\.cursor\mcp.json on Windows) for every project, or .cursor/mcp.json inside a single project. See Cursor's Model Context Protocol guide.

1. Open the file.

   Windows (PowerShell):

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.cursor" | Out-Null; notepad "$env:USERPROFILE\.cursor\mcp.json"

   macOS (Terminal):

   mkdir -p ~/.cursor && touch ~/.cursor/mcp.json && open -e ~/.cursor/mcp.json

   Linux:

   mkdir -p ~/.cursor && nano ~/.cursor/mcp.json

2. Add the server:

   {
     "mcpServers": {
       "zotero": {
         "type": "stdio",
         "command": "/path/to/zotero-mcp",
         "env": {
           "ZOTERO_USER_ID": "${env:ZOTERO_USER_ID}",
           "ZOTERO_API_KEY": "${env:ZOTERO_API_KEY}"
         }
       }
     }
   }

   ${env:NAME} copies each variable from Cursor's environment when the server starts, so the key is not stored in the file.

3. Save the file and check it.

   Windows (PowerShell):

   Get-Content "$env:USERPROFILE\.cursor\mcp.json" -Raw | ConvertFrom-Json

   macOS and Linux:

   python3 -m json.tool ~/.cursor/mcp.json

4. Restart Cursor.

5. Check the connection: Customize in Cursor's sidebar lists zotero with its tools and lets you turn it on or off. If it does not connect, open the Output panel (Ctrl+Shift+U, or ⌘⇧U on macOS) and choose MCP Logs.

On macOS and Linux, ${env:...} finds the values only if Cursor has them, which is usually the case only when you start Cursor from a terminal. If the server reports Unconfigured, replace the two ${env:...} references with your values, and keep the file private.

VS Code with GitHub Copilot

1. Open the Command Palette (Ctrl+Shift+P, or ⌘⇧P on macOS) and run MCP: Open User Configuration.

2. Add the server. VS Code uses servers, not mcpServers:

   {
     "servers": {
       "zotero": {
         "type": "stdio",
         "command": "/path/to/zotero-mcp"
       }
     }
   }

3. Save the file. VS Code underlines any JSON error in the editor.

4. Check the connection: run MCP: List Servers, choose zotero, and start it if it is not running.

On macOS and Linux, if the server reports Unconfigured, add an env object with your two values to this entry, as in the macOS example for Claude Desktop, and keep the file private. The MCP configuration reference describes every field.

ChatGPT desktop app and Codex

The ChatGPT desktop app, the Codex CLI, and the Codex IDE extension share ~/.codex/config.toml (%USERPROFILE%\.codex\config.toml on Windows). See OpenAI's MCP guide.

1. Open the file.

   Windows (PowerShell):

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex" | Out-Null; notepad "$env:USERPROFILE\.codex\config.toml"

   macOS (Terminal):

   mkdir -p ~/.codex && touch ~/.codex/config.toml && open -e ~/.codex/config.toml

   Linux:

   mkdir -p ~/.codex && nano ~/.codex/config.toml

2. Add these lines at the end of the file:

   [mcp_servers.zotero]
   command = "/path/to/zotero-mcp"
   env_vars = ["ZOTERO_USER_ID", "ZOTERO_API_KEY"]
   startup_timeout_sec = 30

   On Windows, write the path in single quotes, for example command = 'C:\Users\you\.local\bin\zotero-mcp.exe'.

3. Save the file and restart the app, or start a new Codex session.

4. Check the connection: in the Codex CLI, codex mcp list shows the server. In any of the apps, the check in Step 5 works too.

env_vars forwards the two variables from the app's environment, so the key stays out of the file. On macOS and Linux, the app may not have the variables, for example when you start it from the Dock. If the server reports Unconfigured, add your values below the entry instead, and keep the file private:

[mcp_servers.zotero.env]
ZOTERO_USER_ID = "YOUR_USER_ID"
ZOTERO_API_KEY = "YOUR_API_KEY"

ChatGPT in a web browser cannot start programs on your computer, so it cannot use this server.

Google Antigravity

Antigravity reads ~/.gemini/config/mcp_config.json (%USERPROFILE%\.gemini\config\mcp_config.json on Windows). See Antigravity's MCP guide.

1. Open the file.

   Windows (PowerShell):

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.gemini\config" | Out-Null; notepad "$env:USERPROFILE\.gemini\config\mcp_config.json"

   macOS (Terminal):

   mkdir -p ~/.gemini/config && touch ~/.gemini/config/mcp_config.json && open -e ~/.gemini/config/mcp_config.json

   Linux:

   mkdir -p ~/.gemini/config && nano ~/.gemini/config/mcp_config.json

2. Add the server:

   {
     "mcpServers": {
       "zotero": {
         "command": "/path/to/zotero-mcp"
       }
     }
   }

3. Save the file and check it.

   Windows (PowerShell):

   Get-Content "$env:USERPROFILE\.gemini\config\mcp_config.json" -Raw | ConvertFrom-Json

   macOS and Linux:

   python3 -m json.tool ~/.gemini/config/mcp_config.json

4. Restart Antigravity.

5. Check the connection: Additional Options (…) → MCP Servers lists zotero and its tools.

Antigravity passes its environment to the server, so the entry needs no env block. On macOS and Linux, if the server reports Unconfigured, add an env object with your two values, as in the macOS example for Claude Desktop. Antigravity's config does not expand variable references, so write the values themselves, and keep the file private.

opencode

opencode reads ~/.config/opencode/opencode.json (%USERPROFILE%\.config\opencode\opencode.json on Windows). If you already keep your settings in opencode.jsonc in the same folder, edit that file instead. See opencode's MCP servers guide.

1. Open the file.

   Windows (PowerShell):

   New-Item -ItemType Directory -Force "$env:USERPROFILE\.config\opencode" | Out-Null; notepad "$env:USERPROFILE\.config\opencode\opencode.json"

   macOS (Terminal):

   mkdir -p ~/.config/opencode && touch ~/.config/opencode/opencode.json && open -e ~/.config/opencode/opencode.json

   Linux:

   mkdir -p ~/.config/opencode && nano ~/.config/opencode/opencode.json

2. Add the server inside mcp:

   {
     "mcp": {
       "zotero": {
         "type": "local",
         "command": ["/path/to/zotero-mcp"],
         "enabled": true,
         "environment": {
           "ZOTERO_USER_ID": "{env:ZOTERO_USER_ID}",
           "ZOTERO_API_KEY": "{env:ZOTERO_API_KEY}"
         }
       }
     }
   }

   opencode replaces {env:NAME} with the variable's value when it loads the file.

3. Save the file and check it. (A .jsonc file that contains comments fails this check even when it is correct.)

   Windows (PowerShell):

   Get-Content "$env:USERPROFILE\.config\opencode\opencode.json" -Raw | ConvertFrom-Json

   macOS and Linux:

   python3 -m json.tool ~/.config/opencode/opencode.json

4. Restart opencode, then run the check in Step 5.

Other MCP clients

Any client that can start a local MCP server needs these settings:

Perplexity's MCP documentation covers connecting other clients to Perplexity, not starting a local server from the Perplexity app.

Step 5: Check that it works

1. Open a new chat in an agent you set up. In VS Code, use Copilot Chat in Agent mode.

2. Ask: Search my Zotero library for <a word from a title you know>.

3. If the agent asks for permission to use a Zotero tool, allow it.

4. The agent calls search_zotero and lists matching items. Each comes with an eight-character item key, such as ABCD1234.

If the agent does not list Zotero tools, or a tool reports Unconfigured, see Troubleshooting.

Use the tools

Ask in plain language; the agent picks the tool. Some examples:

Search results and item lists come one page at a time. To get the next page, call again with start set to the returned next_start, until next_start is null; list_zotero_collections returns your collections in one result. Item keys are eight letters or digits. Zotero documents write requests in Write Requests and File Uploads.

The tools that take a file need its full path, such as C:\drafts\paper.docx on Windows or /Users/you/Documents/paper.docx on macOS. A path that starts with ~ is not expanded.

The tools are also plain Python functions. Install the package into a Python environment (python -m pip install git+https://github.com/Jayaram-Nambiar/zotero-mcp.git), then:

from zotero_mcp.server import search_zotero

page = search_zotero("vaswani attention")
for match in page.matches:
    print(match.item_key, match.title)

Create Word citations

Plain text such as (Smith, 2020) or a pasted reference is not a Zotero citation: the Word plugin works with Word fields. Zotero explains how it stores them in Why do I see ADDIN ZOTERO_ITEM CSL_CITATION?. This server writes those fields for you from simple markers.

1. Find the item keys. Ask your agent, for example: Search my Zotero library for "Attention is all you need" and give me the item key.

2. Write markers in your document where each citation belongs, and one marker where the bibliography belongs:

   {{zotero:ABCD1234}}
   {{zotero:ABCD1234+EFGH5678}}
   {{zotero:ABCD1234|locator=12|label=page}}
   {{zotero:ABCD1234|prefix=see|suffix=.}}
   {{zotero:ABCD1234|suppress-author=true}}
   {{zotero:bibliography}}

   • ABCD1234 is an item key. A plus sign joins several items into one citation.

   • locator adds a page or other location. label names it and defaults to page; other CSL labels include chapter, figure, paragraph, and volume.

   • prefix adds text before the citation, and suffix adds text right after it. Spaces at the start and end of an option's value are ignored.

   • suppress-author=true leaves the author's name out of the citation.

   • {{zotero:bibliography}} marks where the reference list goes.

   • Spaces are allowed just inside the braces, as in {{ zotero:ABCD1234 }}. Write zotero in lowercase, directly followed by a colon. A marker that does not follow this pattern stays in the document as plain text.

3. Save the document as .docx.

4. Ask the agent to convert it, with the document's full path, for example: Turn the citation markers in C:\drafts\paper.docx into Zotero citations using the apa style. The agent calls embed_zotero_word_fields, which writes a new file, paper.zotero.docx, next to the original, and reports how many citations it wrote. If that number is smaller than the number of citation markers, a marker was mistyped and left as plain text.

5. Open the new file in Word, go to the Zotero tab, and choose Refresh. Refresh formats every citation and the bibliography in the chosen style. Until then, the citations show a readable stand-in, such as 1 or (Smith, 2020).

6. Change the style later with Zotero → Document Preferences.

style is a Zotero style name such as vancouver (the default) or apa, or a full https://www.zotero.org/styles/... URL. locale defaults to en-US. From Python:

from zotero_mcp.server import embed_zotero_word_fields

print(embed_zotero_word_fields(r"C:\drafts\paper.docx", style="apa"))

What to know before you convert:

• A paragraph that contains a marker is rebuilt from its plain text plus the new citation fields. Everything else in that paragraph is lost:

  • formatting such as bold and italics;

  • hyperlinks (their text stays);

  • images, footnote and endnote references, and comments;

  • tracked changes and the text inside them;

  • content controls;

  • other fields. A citation inserted earlier with the Zotero plugin becomes plain text.

  Accept or reject tracked changes first, and put markers in plain paragraphs of text.

• Markers are found in body paragraphs, table cells, and each section's main header and footer. Footnotes, text boxes, and first-page or even-page headers are not scanned.

• The fields are Word fields. LibreOffice stores Zotero citations as reference marks, which this server does not write.

• Citations link to your personal library through your user ID. zotero_api can still reach a group library with a groups/GROUPID/... path. A collaborator on another Zotero account sees the embedded citation data and can restyle it, but Refresh updates the live item data only for the account that owns the user ID.

Update, pin, or remove

Update

1. Update to the newest version on GitHub:

   uv tool upgrade zotero-mcp

   This installs the newest commit on the main branch. To stay on a specific release instead, pin a version.

2. Restart your agents so that they start the new version. Quit Claude Desktop from the notification area or menu bar, as in Claude Desktop.

3. Run uv tool list to see the installed version.

On Windows, a running server keeps its files open. If the upgrade stops with Failed to install entrypoint or being used by another process, quit every agent, then install again:

uv tool install --force git+https://github.com/Jayaram-Nambiar/zotero-mcp.git

Pin a version

Each release has a tag, such as v1.0.2; CHANGELOG.md lists them. To install one release and stay on it:

uv tool install --force git+https://github.com/Jayaram-Nambiar/zotero-mcp.git@v1.0.2

uv tool upgrade leaves a pinned version alone. To move to another release, run the same command with that release's tag. To follow the newest version again, run the install command from Step 3 with --force.

Remove

1. Uninstall the server:

   uv tool uninstall zotero-mcp

2. Delete the zotero entry from each agent's config file from Step 4, and run that agent's check command afterwards. Quit Claude Desktop before you edit its file. For Claude Code, run claude mcp remove zotero -s user.

3. Optional: delete the two variables.

   Windows (PowerShell):

   [Environment]::SetEnvironmentVariable("ZOTERO_USER_ID", $null, "User")
   [Environment]::SetEnvironmentVariable("ZOTERO_API_KEY", $null, "User")

   macOS and Linux: delete the two export ZOTERO_... lines from your shell's startup file, such as ~/.zshrc or ~/.bashrc.

4. Optional: revoke the API key on the API keys page.

Keep a single installation of the server. Agents that point at different copies run different versions.

Troubleshooting

Connection status and logs

For more detail, add LOG_LEVEL with the value DEBUG to the server's environment in the agent's config. The server writes its log to standard error, never to the protocol stream.

Ask for help

Open an issue with your operating system, the agent, the output of uv tool list, and the exact error message. Never include your API key, and write YOUR_USER_ID in place of your user ID, which also appears in logs.

Security

• The API key is the key to your library. Use a key with only the access agents need, and leave write access off unless they must change your library.

• Prefer environment variables and config references (${env:...}, env_vars, {env:...}) over pasting the key into config files. Keep any file that holds the key itself private.

• The server sends the key only to api.zotero.org, as a request header. It never returns the key in a tool result and removes it from error messages.

• If the key leaks, revoke it on the API keys page, create a new one, store it as in Step 2, and update any config file that holds the old key.

SECURITY.md explains how to report a vulnerability and lists the server's safeguards.

Contributing

Bug reports and pull requests are welcome. CONTRIBUTING.md explains how to set up a development environment, run the tests, and prepare a change. The test suite runs automatically on Windows, macOS, and Linux for every push to main and every pull request.

Acknowledgements

• Zotero is developed by the Corporation for Digital Scholarship. The local API, Web API, and Word plugin are theirs.

• The Model Context Protocol defines how this server talks to agents.

• Citation formatting uses the Citation Style Language.

• Word documents are written with python-docx.

Disclaimer

This project is not affiliated with, endorsed by, or supported by Zotero or the Corporation for Digital Scholarship. Zotero is a trademark of the Corporation for Digital Scholarship. Use of the Zotero API is subject to Zotero's own terms and documentation. You are responsible for the API key you create and for the library changes an agent makes with it.

The Word fields follow the field format that Zotero documents and that its Word plugin reads. Refresh the document in Word before you rely on the citation style.

License

MIT. Copyright (c) 2026 Jayaram Nambiar.