Skip to main content
Glama
statzhero

zotero-fulltext

by statzhero
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

MCP Server PyPI License: MIT

Access your Zotero library with your favorite AI tool.

Demo

This MCP server for Zotero 8+ gives Claude and Codex access to your library via search and citekeys. It talks directly to Zotero's local API and aims to keep token usage low. Fulltext is fetched only on demand.

Quick Start

  1. Make sure Zotero 8+ is running with the local API enabled (Settings → Advanced → "Allow other applications on this computer to communicate with Zotero").

  2. Install the Claude Code plugin:

/plugin marketplace add statzhero/zotero-fulltext
/plugin install zotero@zotero-fulltext

  1. Run /mcp to confirm the server is connected, then try a slash command:

/zotero:find sustainability reporting

Also works with Claude Desktop, Codex, and as a standalone MCP server without slash commands.

Related MCP server: zotero-mcp

Commands

The Claude Code plugin provides four slash commands:

Command

What it does

/zotero:find <query>

Search the whole library

/zotero:lookup <citekey>

Exact citekey metadata lookup

/zotero:read <citekey>

Numbered fulltext paragraphs

/zotero:within <citekey> <query>

Search inside one paper's fulltext

find searches the whole library. lookup is lightweight metadata confirmation. read returns the actual paper text. within searches only one item's indexed fulltext.

Without the plugin, all the same functionality is available through the MCP tools directly (see Tools).

Installation

Claude Code (plugin with slash commands)

/plugin marketplace add statzhero/zotero-fulltext
/plugin install zotero@zotero-fulltext

This installs the MCP server and slash commands. Run /mcp to confirm the server is connected.

Claude Desktop

Requires uv (install with brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh).

Open Claude Desktop → Settings → Developer → Edit Config, and add:

{
  "mcpServers": {
    "zotero": {
      "type": "stdio",
      "command": "uvx",
      "args": ["zotero-fulltext"]
    }
  }
}

Save the file, then fully quit and reopen Claude Desktop (closing the window is not enough). Open a new chat and confirm the server is available.

Codex (plugin with skills)

Note: The Codex plugin marketplace is still rolling out. The install flow below may change.

codex plugin marketplace add statzhero/zotero-fulltext
codex plugin install zotero

This installs the MCP server and four skills (find, lookup, read, within).

Codex (manual MCP only)

Requires uv (install with brew install uv or curl -LsSf https://astral.sh/uv/install.sh | sh).

Add to ~/.codex/config.toml:

[mcp_servers.zotero]
command = "uvx"
args = ["zotero-fulltext"]

Restart Codex, then run codex mcp list to verify the server appears.

Design

The server is intentionally simple and read-only. It relies on Zotero's own search index rather than building a second one.

  • Startup builds a metadata index mapping citekeys to items and attachments.

  • Library changes are tracked with Zotero version headers and incremental sync.

  • Fulltext is fetched only on demand and cached in memory (TTL/LRU).

  • All outputs are bounded by default: 10 search hits, 80 paragraphs with a character budget, 20 fulltext matches.

  • Item results include item_uri and fulltext_uri so clients can attach standard zotero://... resources directly.

  • Creator roles (author, editor, translator, etc.) are preserved and grouped in results.

  • If a lookup finds no citekey, it returns found=false. If a search finds nothing, it returns results=[]. There is no web fallback.

Tools

The server exposes five MCP tools. The slash commands above are convenience wrappers.

lookup(citekey)

Exact citekey lookup. Citekeys are resolved in order:

  1. Native Zotero 8 citationKey

  2. Legacy Better BibTeX Citation Key: line in Extra

  3. Deterministic generated fallback

If an item later gains a real citekey, the generated key is kept as an alias.

search(query, collection?, tag?, limit?)

Searches Zotero with qmode=everything, collapses attachment hits to parent items, and ranks exact citekey matches first.

collections()

Lists collections in the current library.

fulltext(citekey, offset?, limit?)

Fetches indexed attachment fulltext, splits it into numbered paragraphs, and returns a bounded slice (default: 80 paragraphs). Large extracted paragraphs are split into smaller chunks, and each response has a soft character budget. If the response includes truncated=true, request the same citekey again with offset=next_offset to continue reading.

Fulltext responses include paging metadata:

Field

Meaning

paragraph_count

Total available paragraph chunks for the item

returned_count

Number of paragraph chunks in this response

returned_chars

Approximate text characters returned

max_chars

Character budget used for this response

truncated

Whether more paragraph chunks remain

next_offset

Offset to pass into the next fulltext call, or null when complete

fulltext_search(citekey, query, before?, after?, limit?)

Searches within a single item's paragraphized fulltext and returns matching paragraphs with surrounding context.

Environment Variables

By default the server connects to a local personal library with no authentication. Set these variables to change that:

Variable

Default

Description

ZOTERO_LIBRARY_TYPE

user

user for personal libraries, group for group libraries

ZOTERO_LIBRARY_ID

0

Zotero user or group ID (required for group libraries)

ZOTERO_API_KEY

—

API key for authenticated or remote access

ZOTERO_API_BASE_URL

http://127.0.0.1:23119/api

Base URL for the Zotero API

ZOTERO_MAX_PARAGRAPH_CHARS

1800

Maximum characters per returned fulltext chunk

ZOTERO_MAX_FULLTEXT_CHARS

60000

Soft character budget for each fulltext response; continue with next_offset

ZOTERO_CACHE_DIR

~/.cache/zotero-fulltext

Directory for the persistent metadata index

ZOTERO_STARTUP_SYNC

true

Sync the library index once at startup

ZOTERO_INDEX_REFRESH_MIN_INTERVAL_SEC

15

Minimum seconds between incremental index refreshes

ZOTERO_PARAGRAPH_CACHE_TTL_SEC

7200

Time-to-live for cached fulltext paragraphs

ZOTERO_PARAGRAPH_CACHE_SIZE

128

Maximum number of documents kept in the paragraph cache

ZOTERO_DEFAULT_SEARCH_LIMIT

10

Default number of search results

ZOTERO_DEFAULT_FULLTEXT_LIMIT

80

Default number of paragraphs per fulltext response

ZOTERO_DEFAULT_FULLTEXT_CONTEXT

1

Default paragraphs of context around each fulltext_search match

ZOTERO_USER_ID is accepted as an alias for ZOTERO_LIBRARY_ID. The ZOTERO_LIBRARY_ID default of 0 applies to user libraries; group libraries require an explicit ID.

Example for a group library in Claude Code:

{
  "mcpServers": {
    "zotero": {
      "type": "stdio",
      "command": "zotero-fulltext",
      "env": {
        "ZOTERO_LIBRARY_TYPE": "group",
        "ZOTERO_LIBRARY_ID": "12345"
      }
    }
  }
}

Related Projects

Other MCP servers for Zotero, with different design goals:

  • 54yyyu/zotero-mcp — Feature-rich: read-write operations, optional semantic search via ChromaDB, Web API support. Heavier dependencies.

  • kujenga/zotero-mcp — Minimal read-only server with Web API support via pyzotero. No citekey resolution or in-document search.

  • kaliaboi/mcp-zotero — Cloud-only (Zotero Web API). Metadata browsing, no fulltext.

To remove an existing Zotero MCP server before switching:

claude mcp remove zotero

Or delete the zotero entry from .mcp.json / claude_desktop_config.json / ~/.codex/config.toml manually.

Requirements

  • Zotero 8+ with the local API enabled

  • Python 3.11+

  • Better BibTeX (optional but recommended)

License

MIT • Ulrich Atz (ulrichatz)

Available Tools

5 tools
collectionsA
Read-onlyIdempotent

List Zotero collections in the current library.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, so the description is not required to repeat that. The description adds 'current library' as scoping context, but does not disclose any additional behavioral traits such as whether nested collections are included or how results are ordered.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence that communicates the action, object, and scope with no filler or redundant information. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters, has an output schema, and has annotations covering its safety and idempotency, the description fully covers the necessary context. The one-sentence description is sufficient for a simple list operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the empty schema covers all cases. Per scoring guidelines, a tool with zero parameters receives a baseline of 4 since there is nothing to describe.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'List' with a clear resource 'Zotero collections' and scope 'current library', making its action immediately apparent. It distinguishes itself from sibling tools like 'lookup' and 'search' by explicitly being a listing operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

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 such as 'lookup' or 'search'. The use case is only implied by the name and action, but there is no stated relationship or exclusionary context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fulltextA
Read-onlyIdempotent

Return numbered paragraphs for a Zotero item's indexed fulltext. The citekey is a single token with no spaces (e.g. 'atz2022').

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo
offsetNo
citekeyYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds useful context about 'indexed' fulltext and 'numbered paragraphs' but does not disclose error behavior, missing fulltext handling, or effects of limit/offset.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with front-loaded purpose and a helpful example for the key parameter. Every sentence contributes value with no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return format is covered. However, the description lacks guidance on when to choose this tool over fulltext_search and does not explain pagination parameters, making it adequate but not fully complete for a 3-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It clarifies only the citekey format ('single token with no spaces, e.g. 'atz2022''), but does not explain the semantic meaning of limit and offset (e.g., that limit controls paragraph count), leaving those parameters ambiguous.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Return' and a clear resource 'numbered paragraphs for a Zotero item's indexed fulltext.' It distinguishes from siblings like fulltext_search by specifying an exact output format and per-item scope, even without naming alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when you have a citekey and want an item's fulltext paragraphs, but it does not explicitly state when to use this tool over alternatives like fulltext_search, nor does it provide any when-not-to-use guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lookupA
Read-onlyIdempotent

Look up a Zotero item by its exact citekey (a single token with no spaces, e.g. 'atz2022' not 'atz 2022'). Use this first when you know the citekey.

ParametersJSON Schema
NameRequiredDescriptionDefault
citekeyYes

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint, indicating a safe, repeatable read operation. The description adds a critical behavioral constraint: the citekey must be a single token without spaces, which prevents common input errors. It does not describe error handling for missing items, but the output schema likely covers return values, so the added context goes beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences long, front-loaded with the core purpose, and includes a helpful example. Every sentence adds value: the first defines the tool and input constraint, the second gives a usage priority directive. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple lookup tool with one parameter, read-only annotations, and an output schema, the description covers the essential aspects: what the tool does, the exact input format, and when to use it. The existence of an output schema handles return-value details, leaving no major gaps for this basic operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema only defines 'citekey' as a string with no description (0% coverage). The description fully compensates by explaining that it must be an exact citekey, a single token with no spaces, and provides a concrete example ('atz2022'), making the parameter unambiguous and actionable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the verb 'look up' with the resource 'Zotero item' and the specific method 'by its exact citekey', clearly stating the tool's function. It distinguishes from siblings like 'search' by emphasizing the need for an exact citekey rather than fuzzy or broad search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The instruction 'Use this first when you know the citekey' provides a clear when-to-use directive, implying that when the citekey is unknown, other tools such as 'search' should be used. However, it does not explicitly name the alternative tool, making the guidance clear but not fully explicit about exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.4.0
    • First observedcollections
    • First observedfulltext
    • First observedfulltext_search
    • First observedlookup
    • First observedsearch
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.6/5.0
Disambiguation4/5

Most tools have clear distinct purposes: lookup is for exact citekey metadata, fulltext retrieves paragraphs, search is global, and fulltext_search is scoped to one item. However, search and fulltext_search could be confused since both perform keyword searches, though descriptions help differentiate them.

Naming Consistency2/5

Tool names follow mixed conventions: lookup and search are bare verbs, collections and fulltext are nouns, and fulltext_search is a noun+verb compound. There is no consistent verb_noun or resource_action pattern.

Tool Count5/5

With 5 tools, the server is well-scoped for its purpose of Zotero fulltext retrieval. Each tool covers a distinct need without unnecessary bloat, fitting comfortably in the ideal 3-15 range.

Completeness4/5

The set covers lookup, search, collection listing, fulltext retrieval, and within-item search, which addresses core read-only workflows. Missing collection item listing and broader metadata browsing are minor gaps that can be worked around via search.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • zotero-mcp

    trymybiscottis
    A
    license
    A
    quality
    C
    maintenance
    Read-only MCP server that lets Claude or any MCP client search and retrieve metadata, notes, full text, citations, and BibTeX from your local Zotero library via its built-in API.
    11
    MIT

  • zotero-mcp

    rdesc
    F
    license
    Not graded
    quality
    C
    maintenance
    MCP server for natural-language search over a local Zotero library, enabling tools to search, retrieve, and manage paper metadata, notes, and PDF fulltext via Claude.
    -

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/statzhero/zotero-fulltext'

If you have feedback or need assistance with the MCP directory API, please join our Discord server