Provides read-only access to a local Zotero library via the Zotero desktop local API, with tools for searching items, retrieving metadata and full-text of attachments, and managing collections, tags, and library statistics.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@zotero-mcp search my Zotero library for 'machine learning' in full text"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local-only, read-only MCP server for Zotero.
This tool was built by Claude and hardly verified by me. I advise against using it on your Zotero database (and if you ignore that advise, make sure you have up to date offline backups).
Related MCP server: zotero-mcp
Local-only. Talks to the Zotero desktop client's local API on
127.0.0.1:23119. No API key, no zotero.org account, no network traffic.
Read-only. Every tool is a retrieval call, enforced by an allowlist; the
server has no code path that can add, edit, or delete anything. Note that the
local API itself is not read-only — Zotero 10+ supports POST/PUT/
PATCH/DELETE on /api/ once a client obtains a local API key via
POST /api/local/authorize. This server never requests such a key and holds
api_key=None, so the write path stays unreachable; the read-only guarantee
is enforced here, not by the API.
stdio transport only.
Zotero 7 or newer, running
Python 3.13+
Zotero's local API enabled: Settings → Advanced → "Allow other applications on this computer to communicate with Zotero"
Without that setting the API returns 403 and every tool reports how to fix it.
From a local checkout:
uv tool install .Register it with Claude Code:
claude mcp add zotero -- uvx zotero-mcpOr add it to your MCP client config directly:
{
"mcpServers": {
"zotero": {
"command": "uvx",
"args": [ "zotero-mcp" ]
}
}
}Tool | Purpose |
| Search all fields, tags and attachment text; results ranked by where the match occurred. Optional item-type and tag filters. |
| Full metadata for one item key. |
| Attachments and notes belonging to an item. |
| Indexed text of an attachment (PDF, snapshot), as plain text with a header line. |
| Collections, optionally top-level only. |
| Items inside a collection. |
| Tags used in the library. |
| Most recently added items. |
| Item and collection counts. |
Item keys are 8-character strings such as ABCD2345. To read a PDF's text,
call get_item_children on a reference first to get its attachment key, then
pass that to get_item_fulltext.
zotero.sqlite directly?Zotero's developer documentation states that the SQLite schema is an internal implementation detail that may change between releases, and that direct access must be read-only to avoid corruption (Zotero's caching layer interferes with SQLite file locking). The local API is the supported interface, works while Zotero is running, and returns stable documented JSON.
The tradeoff: Zotero must be open. Reading the SQLite file would work with Zotero closed, at the cost of coupling to an unstable schema.
itemType negation: the API docs
document exactly three forms — itemType=book, itemType=book || journalArticle
(OR), and itemType=-attachment (NOT). Negating a group is not documented,
and unsupported expressions fail open: they return 200 OK with the
filter silently dropped rather than a 400. Measured on this library:
-attachment → 578 results, -attachment || note → 1184 (the unfiltered
total), -(attachment) → 1184. An unknown type such as garbagetype returns
0 results rather than erroring. Because a broken filter yields more rows
than a working one, this server sends only the documented -attachment and
drops remaining notes and annotations in code, over-fetching so the requested
limit is still filled.
get_item_fulltext returns plain text, not JSON. Every other tool
returns structured records, but a document is a text payload: serialising it
as JSON escapes each newline into a literal \n and collapses the whole
document onto one line (measured: 894 escapes in a single 51,003-char line),
forcing the caller to decode it before reading. The tool returns the text
with a one-line header instead, which preserves line breaks and is slightly
smaller than the escaped JSON was. Returning str alone is not enough:
FastMCP still advertises an output schema and emits {"result": "..."} as
structured content, which clients that prefer structured output render as
JSON — re-escaping the newlines. The tool is therefore declared
@mcp.tool(output_schema=None) so only the plain-text block is sent.
Search ranks, because Zotero only filters. search_items defaults to
qmode="everything" (all fields, tags and indexed attachment text) rather
than the API's titleCreatorYear default. The narrow default made recall
brittle: Zotero requires every whitespace-separated term to match, so
searching KEMTLS post-quantum TLS without handshake signatures returned
zero hits — KEMTLS appears in the abstract, not the title, and that one
term zeroed the query. The same search now finds the paper.
Zotero's quicksearch filters without ranking, so hits are scored locally by
match location — title, then creator/date, tags, abstract/venue, and finally
attachment text — and each result reports its matchedOn. Whole-word matches
outrank substring ones, so searching Shor surfaces Shor's paper above
Shorter Koblitz Curves. qmode="fields" (all fields and tags, no
attachment text) is also accepted; it works on the local API but is not in
the web API docs.
Results are condensed (envelope and empty fields stripped) to keep responses
small; abstracts are truncated in list views but returned in full by
get_item.
ZOTERO_LIBRARY_ID and ZOTERO_LOCALE can override the defaults (0,
en-US).
uv run pytestThe suite mocks pyzotero, so it runs without Zotero open.
Released into the public domain under the Unlicense. See LICENSE.
List the items inside a collection.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | 8-character Zotero collection key. | |
| limit | No | Maximum number of results (1-100). | |
| top_level_only | No | Return only top-level items, hiding attachments and notes. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description must carry the burden of behavioral disclosure. It merely says 'list,' implying a read-only operation, but does not mention pagination, default top-level filtering, authentication requirements, or any side effects or edge cases. This is a significant gap for behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence with no wasted words or redundant content. It is front-loaded and immediately conveys the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The presence of a full output schema and complete parameter descriptions reduces the need for the description to explain return values or parameters. However, the description lacks usage context and behavioral details that would help an agent select the tool in ambiguous situations. It is adequate but not thorough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides exhaustive descriptions for all three parameters (key, limit, top_level_only), covering 100% of the schema. The description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'list' and identifies the resource as 'items inside a collection,' which clearly distinguishes it from siblings like get_item (single item), list_collections (collections), and get_item_children (children of an item). It is unambiguous and precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as get_item_children or search_items. It does not state any prerequisites, exclusions, or context in which another tool would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get full metadata for a single item by its key.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | 8-character Zotero item key, e.g. 'ABCD2345'. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden for behavioral disclosure. It implies a read-only operation via 'Get' but does not state error behavior (e.g., what happens if the key is not found), authentication requirements, or response format details beyond the output schema. The lack of any additional behavioral context leaves gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no redundant wording. It is front-loaded with the core action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-item fetch with a well-documented schema and an output schema available, the description is largely sufficient. The only gap is the lack of behavioral context (e.g., error handling or permissions), but the simplicity of the tool keeps the completeness high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for the single parameter 'key', including its type, format, and example. The description adds no extra semantic meaning, so the baseline score of 3 applies since the schema already documents the parameter thoroughly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Get full metadata for a single item by its key' clearly states a specific verb (Get) and resource (full metadata for a single item). It distinguishes itself from siblings like get_item_children and get_item_fulltext by focusing on the complete metadata of one item.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies using this tool when you have a key and need full metadata, but it provides no explicit guidance on when to use this vs alternatives like search_items or get_recent_items. There are no exclusions or alternative recommendations, leaving the agent to infer context from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the attachments and notes attached to an item.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | 8-character Zotero item key, e.g. 'ABCD2345'. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the burden of behavioral disclosure. The verb 'List' implies a read-only operation, but the description does not elaborate on output format, ordering, or any edge cases like missing attachments. It adds only minimal context beyond the action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that directly states the function without any filler. Every word earns its place, and the key information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has only one parameter and an output schema is present, the description is mostly sufficient. However, it does not clarify whether 'attachments and notes' includes all child items or just direct ones, nor does it mention any pagination or limits. Still, for a simple list operation, the description is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides a complete description of the 'key' parameter including format and an example, so the schema coverage is 100%. The tool description contributes no additional parameter information, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists attachments and notes for a specific item, which distinguishes it from sibling tools like get_item (metadata) and get_item_fulltext (content). The verb 'List' and resource 'attachments and notes attached to an item' provide a specific and unambiguous purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as get_item or search_items. It also doesn't mention any prerequisites or exclusions, leaving the agent to infer usage solely from the purpose.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the indexed full text of an attachment (PDF, snapshot, etc.).
The key must be an attachment item key, not its parent. Use get_item_children on a reference to find its attachment keys. Text is only available if Zotero has indexed the attachment.
| Name | Required | Description | Default |
|---|---|---|---|
| key | Yes | 8-character Zotero item key, e.g. 'ABCD2345'. | |
| max_chars | No | Truncate the returned text to this many characters. |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It clearly communicates that the tool returns text only if Zotero has indexed the attachment, and that the key type matters. However, it does not explicitly state whether this is a read-only operation or what happens when text is unavailable (e.g., empty result vs. error). This is a minor gap, but the main behaviors are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences, each earning its place. It starts with a clear purpose, then provides key-related guidance, and ends with a critical limitation. There is no redundancy or fluff, and the structure front-loads the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is relatively simple with only two parameters and an existing output schema (which explains return values). The description covers the essential context: what the tool does, what key to use, and a key limitation. It could mention error behavior when text isn't indexed, but overall it is sufficiently complete for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers both parameters with helpful descriptions (e.g., max_chars truncation). The description adds critical semantic context beyond the schema for the 'key' parameter by specifying it must be an attachment item key, not its parent. This is a valuable addition, though it does not add extra info for max_chars beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Get the indexed full text of an attachment (PDF, snapshot, etc.)'. The verb 'Get' and the specific resource (full text of an attachment) make the purpose unambiguous. It also distinguishes itself from siblings like get_item (metadata) and get_item_children (finding attachment keys) by explicitly narrowing the scope to full text extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: the key must be an attachment item key, not the parent, and it directs users to get_item_children to find attachment keys. It also notes the indexing requirement, clarifying when the tool will be useful. This goes beyond simple 'when to use' by naming a specific alternative and stating a precondition.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the most recently added items in the library.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (1-100). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description carries the full burden. It discloses only that items are ordered by recency, but does not describe pagination behavior, return format, whether the limit is strictly enforced, or potential edge cases. This is minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the verb and resource, containing no extraneous words or redundant details. It is highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with one optional parameter and an output schema (per context signals), so return details are covered. However, the description lacks any mention of ordering specifics, item scope, or behavioral nuances that would be useful for a tool without annotations. It is adequate but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%: the single 'limit' parameter is fully described with type, default, min, max, and a clear description. The tool description adds nothing beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'List the most recently added items in the library' with a specific verb (List) and resource (items), plus a qualifier ('most recently added') that distinguishes it from sibling tools like get_item (single item) and search_items (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no explicit guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or alternative tools for filtered listing. The sibling names are visible in context, but the description itself gives no usage direction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report totals for the library: item counts and collection count.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It clearly indicates a read-only reporting action ('Report totals') and specifies the outputs (item counts, collection count). Although it doesn't discuss performance or edge cases, the presence of an output schema reduces the need to describe return values. The behavior is adequately transparent for a simple stats tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the verb ('Report') and provides a clear scope with a colon-separated detail. Every word earns its place; there is no redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (no parameters), the description is nearly complete. It states what is counted (items and collections) and the output schema covers return values. However, it does not provide context about the scope ('the library') or how this compares to sibling tools, which might be useful but is not critical for such a simple tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema is empty (0 parameters), so the baseline is 4. The description does not need to explain any parameters, and it adds no param-specific information because none exist. No additional meaning is required beyond what the schema already trivially covers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'Report totals for the library' and specifies what totals (item counts and collection count). This distinguishes it from sibling tools that focus on individual items, searches, or collections.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives. The intended use is implied by the nature of the tool (aggregate stats), but there is no direct comparison or prerequisite mentioned. It would benefit from a note like 'Use instead of list_collections when you need summary counts.'
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List collections (folders) in the library.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (1-100). | |
| top_level_only | No | Return only top-level collections, not subcollections. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It offers no details on default behavior (e.g., whether subcollections are included by default), pagination, ordering, or output format. The parameter top_level_only hints at hierarchy, but the description itself adds no behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, succinct sentence that immediately conveys the core purpose without any redundant words. It is well-structured and front-loaded with the action verb and resource.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While the tool is relatively simple and has an output schema, the description lacks context on when to use it and doesn't mention any behavioral nuances. However, given the minimal risk of a read-only list operation and the schema covering parameter details, it is moderately complete but not exemplary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides comprehensive descriptions for both parameters (limit and top_level_only) with 100% coverage. The tool description adds no additional meaning beyond the schema, so the baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('List') and resource ('collections (folders) in the library'). It differentiates from siblings like get_collection_items, which lists items within a collection, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like get_collection_items or search_items. There is no mention of exclusions, prerequisites, or typical use cases. It only states the basic action without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List tags used in the library.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum number of results (1-100). |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It states only the basic action and does not reveal any behavioral traits such as whether tags are sorted, whether only used tags are returned, whether counts are included, or how the limit parameter affects results. For a read-only list operation, this lack of detail hampers an agent's ability to predict tool output characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that fully communicates the tool's primary purpose without any filler. It is front-loaded and easy to parse. It earns a 4 rather than a 5 because, while concise, it omits potentially useful details such as output characteristics, but the brevity itself is not a flaw.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple: one optional parameter, an output schema exists, and the description conveys the core function. However, it does not mention behavioral nuances like the limit parameter's effect, whether tags with zero items are included, or how results are ordered. Given the presence of an output schema, the description is minimally viable but lacks contextual richness that would help an agent use the tool fully.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single optional 'limit' parameter, so the schema already documents its meaning. The description adds no additional parameter information beyond what the schema provides. The baseline of 3 applies because the schema carries the parameter explanation, and the description does not need to compensate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: 'List tags used in the library.' It specifies a concrete verb ('List') and resource ('tags') with a clear scope ('in the library'). This is unambiguous and distinct from sibling tools like list_collections, which target collections rather than tags.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives such as search_items or list_collections. There is no mention of use cases, exclusions, or differences from sibling tools. The description is entirely silent on usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the Zotero library for items matching a query.
Returns condensed metadata for each match. Attachments and notes are excluded so results are actual references; use get_item_children to see an item's PDFs and notes.
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | Filter by tag. Use '||' for OR, and '-' prefix to negate. | |
| limit | No | Maximum number of results (1-100). | |
| qmode | No | 'titleCreatorYear' searches titles/creators/year; 'everything' also searches full-text content of attachments. | titleCreatorYear |
| query | Yes | Search text. Matches title and creators by default. | |
| item_type | No | Filter by item type, e.g. 'journalArticle', 'book'. Supports Zotero boolean syntax such as 'book || bookSection' and '-attachment' to exclude. |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavior. It adds useful context: returns condensed metadata, excludes attachments/notes, and points to an alternative. However, it doesn't elaborate on other potential behaviors like rate limits or authentication, though such info may not be critical for a search tool. The provided details go beyond the schema and are genuinely useful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, with the primary purpose front-loaded in the first sentence and crucial exclusions/alternatives in the second. Every word earns its place, and the structure is clean and immediately scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity, the schema fully documents all 5 parameters with clear descriptions, and an output schema exists (so return format need not be explained). The description covers the key remaining aspects: purpose, exclusions, and an explicit alternative. This is complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description does not add parameter-level details beyond what the schema already provides (e.g., tag boolean syntax, qmode enum, item_type filtering). It only mentions 'query' generically, which adds no semantic value beyond the schema's own description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific verb and resource: 'Search the Zotero library for items matching a query.' It further clarifies the scope by noting that results are 'condensed metadata' and that 'attachments and notes are excluded,' distinguishing it from sibling tools like get_item_children which retrieve attachments/notes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly provides an alternative: 'use get_item_children to see an item's PDFs and notes.' This tells the agent when not to use this tool and what to use instead, satisfying the when/when-not/alternatives criterion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct operation: retrieving single items, searching, listing attachments, getting fulltext, browsing collections/tags, and library stats. There is no meaningful overlap between tool purposes, and descriptions clarify edge cases like attachment keys.
Most tools follow a verb_noun pattern (get_item, list_collections, search_items), with 'get' for single-item retrieval and 'list' for enumerations. The only outlier is library_stats, which uses a noun-noun form, slightly breaking the pattern.
With 9 tools, the server is well-scoped for a Zotero library read-only workflow. Each tool covers a distinct aspect of browsing and retrieving references, without unnecessary redundancy or excessive granularity.
The toolset covers the core read operations: item retrieval, search, attachments, fulltext, collections, tags, and recent items. Missing write operations (create/update/delete) are likely intentional for a reference-manager assistant, and a method to list all items at once is absent but can be approximated via search.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Remote MCP server for full read/write access to a Zotero library
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Search your Glasp web and Kindle highlights, notes, and AI memories from any MCP client. Read-only.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/sebastianv89/zotero-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
