이 프로젝트는 Zotero 용 모델 컨텍스트 프로토콜(MCP)을 구현하는 파이썬 서버로, AI 어시스턴트 내에서 Zotero 라이브러리에 접근할 수 있도록 합니다. MCP 클라이언트 에서 사용할 수 있도록 작지만 최대한 유용한 Zotero 상호작용 세트를 구현하는 것을 목표로 합니다.
이 MCP 서버는 다음과 같은 도구를 제공합니다.
zotero_search_items : 텍스트 쿼리를 사용하여 Zotero 라이브러리에서 항목을 검색합니다.
zotero_item_metadata : 특정 Zotero 항목에 대한 자세한 메타데이터 정보를 가져옵니다.
zotero_item_fulltext : 특정 Zotero 항목(예: PDF 내용)의 전체 텍스트를 가져옵니다.
이러한 정보는 모든 MCP 클라이언트나 MCP Inspector를 통해 검색하고 접근할 수 있습니다.
각 도구는 Zotero 항목에서 관련 정보가 포함된 서식이 지정된 텍스트를 반환하고, Claude와 같은 AI 도우미는 이를 순차적으로 사용하여 항목을 검색한 다음 메타데이터나 텍스트 콘텐츠를 검색할 수 있습니다.
Related MCP server: zotero-assistant-mcp
이 서버는 Zotero 데스크톱 애플리케이션에서 제공하는 로컬 API 또는 Zotero 웹 API를 통해 실행할 수 있습니다. 로컬 API는 응답 속도가 다소 더 빠르지만, Zotero 앱이 해당 API를 활성화한 동일한 컴퓨터에서 실행되어야 합니다. 로컬 API를 활성화하려면 다음 단계를 따르세요.
Zotero를 열고 "Zotero 설정"을 엽니다.
"고급" 탭에서 "이 컴퓨터의 다른 응용 프로그램이 Zotero와 통신하도록 허용"이라는 상자를 체크하세요.
[!중요] 라이브러리 항목의 전체 콘텐츠를 검색할 수 있는 로컬 API의
/fulltext엔드포인트에 접근하려면 Zotero 베타 빌드 (2025년 3월 30일 기준)를 설치해야 합니다. 7.1이 출시되면 이 기능은 더 이상 제공되지 않습니다. 자세한 내용은 https://github.com/zotero/zotero/pull/5004를 참조하세요. 이 기능을 원하지 않으면 웹 API를 사용하세요.
Zotero 웹 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 : 라이브러리 유형(사용자 또는 그룹, 기본값: 사용자)
uvxClaude Desktop과 uvx 를 사용한 직접 Python 설치와 함께 사용하려면 다음을 mcpServers 구성에 추가하세요.
지엑스피1
--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 sync 실행하여 uv 로 종속성을 설치합니다.
위의 환경 변수를 사용하여 프로젝트 루트에 .env 파일을 만듭니다.
로컬 개발을 위한 MCP 검사기 시작:
npx @modelcontextprotocol/inspector uv run zotero-mcpClaude Desktop에 대해 로컬 저장소를 테스트하려면 이 디렉토리 내의 셸에서 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:localMCP 검사기로 컨테이너를 테스트하려면 다음 명령을 실행하세요.
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