该项目是一个 Python 服务器，它实现了Zotero的模型上下文协议 (MCP) ，使您可以在 AI 助手中访问 Zotero 库。它旨在实现一组规模虽小但极其实用的 Zotero 交互，以便与MCP 客户端配合使用。
该 MCP 服务器提供以下工具：
zotero_search_items ：使用文本查询在 Zotero 库中搜索项目
zotero_item_metadata ：获取有关特定 Zotero 项目的详细元数据信息
zotero_item_fulltext ：获取特定 Zotero 项目的全文（即 PDF 内容）
这些可以通过任何 MCP 客户端或MCP 检查器发现和访问。
每个工具都会返回包含 Zotero 项目相关信息的格式化文本，而 Claude 等 AI 助手可以按顺序使用它们，搜索项目，然后检索其元数据或文本内容。
Related MCP server: zotero-assistant-mcp
该服务器既可以通过 Zotero 桌面应用程序提供的本地 API运行，也可以通过Zotero Web API运行。本地 API 的响应速度可能更快一些，但要求 Zotero 应用程序在同一台计算机上运行并启用该 API。要启用本地 API，请执行以下步骤：
打开 Zotero 并打开“Zotero 设置”
在“高级”选项卡下，选中“允许此计算机上的其他应用程序与 Zotero 通信”框。
重要提示：要访问本地 API 上的
/fulltext端点（该端点允许检索库中项目的完整内容），您需要安装Zotero Beta 版本（截至 2025 年 3 月 30 日）。7.1 版本发布后，此操作将不再适用。更多信息请参阅https://github.com/zotero/zotero/pull/5004 。如果您不想这样做，请改用 Web API。
要使用 Zotero Web API，您需要创建一个 API 密钥，并在 Zotero 帐户设置中找到您的图书馆 ID（通常是您的用户 ID）： https://www.zotero.org/settings/keys
这些是可用的配置选项：
ZOTERO_LOCAL=true ：使用本地 Zotero API（默认值：false，请参阅下面的注释）
ZOTERO_API_KEY ：您的 Zotero API 密钥（本地 API 不需要）
ZOTERO_LIBRARY_ID ：您的 Zotero 图书馆 ID（用户图书馆的用户 ID，本地 API 不需要）
ZOTERO_LIBRARY_TYPE ：库的类型（用户或组，默认：用户）
uvx与本地 Zotero API要将其与 Claude Desktop 一起使用并通过uvx直接安装 python，请将以下内容添加到mcpServers配置中：
{
"mcpServers": {
"zotero": {
"command": "uvx",
"args": ["--update", "zotero-mcp"],
"env": {
"ZOTERO_LOCAL": "true",
"ZOTERO_API_KEY": "",
"ZOTERO_LIBRARY_ID": ""
}
}
}
}--update标志是可选的，它会在有新版本可用时拉取最新版本。如果您尚未安装uvx ，可以使用pipx run代替，或者将此存储库克隆到本地，然后按照下面“开发”部分的说明操作。
如果您想在 Docker 容器中运行此 MCP 服务器，您可以使用以下配置，插入您的 API 密钥和库 ID：
{
"mcpServers": {
"zotero": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e", "ZOTERO_API_KEY=PLACEHOLDER",
"-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER",
"ghcr.io/kujenga/zotero-mcp:main"
],
}
}
}要更新到较新版本，请运行docker pull ghcr.io/kujenga/zotero-mcp:main 。也可以使用基于 docker 的安装与本地 Zotero API 通信，但您需要修改上述命令以确保与 Zotero 应用程序的本地 API 接口具有网络连接。
有关进行更改和对项目做出贡献的信息。
克隆此存储库
通过运行以下命令安装uv依赖项： uv sync
使用上述环境变量在项目根目录中创建一个.env文件
启动MCP Inspector进行本地开发：
npx @modelcontextprotocol/inspector uv run zotero-mcp要针对 Claude Desktop 测试本地存储库，请在此目录中的 shell 中运行echo $PWD/.venv/bin/zotero-mcp ，然后在 Claude Desktop 配置中设置以下内容
{
"mcpServers": {
"zotero": {
"command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp"
"env": {
// Whatever configuration is desired.
}
}
}
}运行测试套件：
uv run pytest使用以下命令构建容器映像：
docker build . -t zotero-mcp:local要使用 MCP 检查器测试容器，请运行以下命令：
npx @modelcontextprotocol/inspector \
-e ZOTERO_API_KEY=$ZOTERO_API_KEY \
-e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
docker run --rm -i \
--env ZOTERO_API_KEY \
--env ZOTERO_LIBRARY_ID \
zotero-mcp:localGet the full text content of a Zotero item, given the item key of a parent item or specific attachment.
| Name | Required | Description | Default |
|---|---|---|---|
| item_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the tool 'Get[s] the full text content', implying a read-only operation, but doesn't disclose behavioral traits such as authentication needs, rate limits, error conditions, or what happens if the item key is invalid. For a tool with zero annotation coverage, this is a significant gap in 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 appropriately sized and front-loaded: a single, clear sentence that states the purpose and parameter context without any wasted words. Every part of the sentence earns its place by conveying essential information efficiently.
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 (1 parameter, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and parameter semantics but lacks details on behavioral aspects, output format, or error handling. Without annotations or an output schema, the description should do more to be complete, but it meets the bare minimum for 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 has 1 parameter with 0% description coverage, so the description must compensate. It adds meaning by explaining that 'item_key' refers to 'a parent item or specific attachment', which clarifies the parameter's purpose beyond the schema's generic 'Item Key' title. However, it doesn't provide details on format, examples, or constraints, leaving some ambiguity.
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 purpose: 'Get the full text content of a Zotero item' with the specific verb 'Get' and resource 'full text content'. It distinguishes from sibling tools like 'zotero_item_metadata' (which likely returns metadata) and 'zotero_search_items' (which searches for items). However, it doesn't explicitly contrast with siblings, so it's not a perfect 5.
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 usage by specifying 'given the item key of a parent item or specific attachment', which provides some context on when to use it. However, it lacks explicit guidance on when to use this tool versus alternatives like 'zotero_item_metadata' for non-full-text data or 'zotero_search_items' for finding items first. No exclusions or prerequisites are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get metadata information about a specific Zotero item, given the item key.
| Name | Required | Description | Default |
|---|---|---|---|
| item_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it's a read operation ('Get'), but doesn't mention whether it requires authentication, rate limits, error conditions (e.g., invalid item keys), or the format of returned metadata. For a tool with zero annotation coverage, this leaves significant gaps in understanding how it behaves beyond the basic purpose.
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, efficient sentence that front-loads the core purpose ('Get metadata information') and includes the key constraint ('given the item key'). There is no wasted text, repetition, or unnecessary elaboration, making it highly concise and well-structured for quick understanding.
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 (1 parameter, no nested objects) but lack of annotations and output schema, the description is minimally complete. It covers the purpose and parameter semantics adequately but misses behavioral details like authentication needs or return format. Without an output schema, the description should ideally hint at what metadata is returned, which it doesn't, leaving room for improvement.
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 description adds meaning by explaining that 'item_key' is used to identify 'a specific Zotero item', which clarifies the parameter's role beyond the schema's generic 'Item Key' title. With 0% schema description coverage and only one parameter, this compensates adequately by providing context, though it doesn't detail the key's format or source. Baseline is high due to low parameter count.
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 verb 'Get' and the resource 'metadata information about a specific Zotero item', making the purpose immediately understandable. It distinguishes from 'zotero_item_fulltext' (which likely retrieves full text content) and 'zotero_search_items' (which searches multiple items) by focusing on metadata retrieval for a single item. However, it doesn't explicitly mention what metadata fields are included, keeping it from a perfect score.
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 usage by specifying 'given the item key', suggesting this tool is for when you have a specific item identifier. It doesn't provide explicit when-to-use guidance versus alternatives like 'zotero_search_items' (e.g., use this for known items, use search for unknown items) or mention prerequisites like authentication. The context is clear but lacks detailed exclusions or comparisons.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for items in your Zotero library, given a query string, query mode (titleCreatorYear or everything), and optional tag search (supports boolean searches). Returned results can be looked up with zotero_item_fulltext or zotero_item_metadata.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| qmode | No | titleCreatorYear | |
| tag | No | ||
| limit | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It describes the search functionality and mentions that results can be looked up with other tools, which adds useful context. However, it doesn't disclose important behavioral traits like whether this is a read-only operation, what permissions are needed, pagination behavior beyond the 'limit' parameter, or error conditions. The description adds some value but leaves significant 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 efficiently structured in two sentences: the first explains the core functionality with key parameters, the second provides important follow-up context about sibling tools. Every word earns its place with no redundancy or fluff.
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 search tool with 4 parameters, 0% schema coverage, no annotations, and no output schema, the description does a reasonable job explaining the search purpose and parameters. However, it lacks information about return format, error handling, authentication requirements, and doesn't fully document all parameters (missing 'limit'). Given the complexity and lack of structured documentation, this leaves significant gaps.
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?
With 0% schema description coverage, the description must compensate. It explains the purpose of 'query', 'qmode' (with specific mode examples), and 'tag' (including boolean search support). It doesn't mention the 'limit' parameter, but covers 3 of 4 parameters with meaningful context beyond their names. This significantly improves understanding compared to the bare schema.
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 verb ('Search for items'), resource ('in your Zotero library'), and scope ('given a query string, query mode... and optional tag search'). It distinguishes from siblings by mentioning that results can be looked up with 'zotero_item_fulltext' or 'zotero_item_metadata', indicating this is a search tool while siblings provide detailed item data.
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 clear context for when to use this tool (searching the library with query parameters) and implicitly distinguishes from siblings by noting that results can be looked up with those tools. However, it doesn't explicitly state when NOT to use this tool or provide alternative search methods within the same tool family.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
zotero_item_fulltextzotero_item_metadatazotero_search_itemsScored across 3 tools
Each tool has a clearly distinct purpose: zotero_search_items finds items, zotero_item_metadata retrieves metadata for a specific item, and zotero_item_fulltext gets full text content. There is no overlap or ambiguity between these functions.
All tools follow a consistent 'zotero_item_*' pattern with snake_case, using descriptive suffixes (fulltext, metadata, search_items) that clearly indicate their specific actions. The naming is uniform and predictable.
With only 3 tools, the server feels thin for a Zotero library management domain. While the tools cover basic search and retrieval, typical library operations like creating, updating, or deleting items are missing, suggesting an incomplete surface.
The tool set is severely incomplete for Zotero library management. It only supports search and read operations (search, get metadata, get fulltext), with no ability to create, update, delete, or manage items, collections, or tags, which are core to the domain.
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Remote MCP server for full read/write access to a Zotero library
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction