How to Use the Zotero MCP in Windsurf

Q: How do I search for specific references using Zotero and Windsurf?

Just tell your agent to find what you need. It uses listitems to pull down all records, or it can narrow the scope by checking a full collection with getcollection. The results show exactly which items match your criteria.

Q: What data types are available when using Zotero and Windsurf?

The agent reads all possible item types via listitemtypes, giving you a full rundown of everything Zotero supports. You can then check the specific fields for any type with getitemtypefields to make sure your data is structured right.

Q: Does Windsurf handle updating item data securely?

Yes. You use updateitem to make partial changes (PATCH) to an existing reference without touching everything else. It only updates the specific fields you point it toward, keeping your original research intact.

Manage your research library automatically using Windsurf's autonomous agent.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Zotero MCP to Windsurf

Create your Vinkius account to connect Zotero to Windsurf and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Zotero with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Build a full bibliography outline.

You set the goal, and Cascade figures out how to get it done. It can check all top-level collections via `list_top_collections` and then list items in each one using `list_collection_items`. You'll see everything you need for your paper—all in context. This process uses the full library, making sure nothing gets missed. Cascade pulls data from multiple sources like checking individual item details with `get_item` or running a deep search through `list_items`.

Organize and clean up reference materials.

Need to get rid of some old junk? Just tell Cascade what you want gone. It handles deleting single references with `delete_item` or clearing out bulk items using `delete_items`. You'll know exactly what it deleted because the tool reports back. It's smart enough to check your trash first, too. Use `list_trash_items` if you suspect something went missing, and then proceed with recovering or deleting those records.

Verify item fields and types.

Don't guess what data points are available; just ask. Cascade reads the valid schema for any reference type using `get_newitem_template` or checks all possible fields with `list_item_fields`. This gives you confidence that your AI client is using the right structure. It also lets you list out everything Zotero knows about item types via `list_item_types`, so you never get stuck on unsupported formats. You're always working with accurate data.

Setup guide

Set up Zotero MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the Zotero MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my Zotero payment history." If connected, Cascade will call the Zotero tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "zotero-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Zotero. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Zotero now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Zotero MCP in Windsurf

Just tell your agent to find what you need. It uses `list_items` to pull down all records, or it can narrow the scope by checking a full collection with `get_collection`. The results show exactly which items match your criteria.

Yep. If you think you trashed something important, the agent can pull down records that were marked as deleted since a specific library version using `get_deleted`. This is a solid safety net for your research notes.

The agent reads all possible item types via `list_item_types`, giving you a full rundown of everything Zotero supports. You can then check the specific fields for any type with `get_item_type_fields` to make sure your data is structured right.

It's simple. You can list all existing tags in the library with `list_tags`, or check for a specific tag name that matches your search criteria using `get_tag`. This keeps your references perfectly categorized.

Yes. You use `update_item` to make partial changes (PATCH) to an existing reference without touching everything else. It only updates the specific fields you point it toward, keeping your original research intact.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript