Zotero MCP Server: sem precisar abrir o Zotero, busca em 10,000 PDF em ~20 ms

Q: O servidor Zotero MCP suporta Python além de JavaScript?

Sim. Existem duas shells com recursos equivalentes: @docsagent/mcp-zotero no npm para usuários de JavaScript/Node e docsagent-mcp-zotero no PyPI para Python 3.10+. As duas expõem as mesmas 8 ferramentas com os mesmos esquemas, códigos de erro e gate de escrita, e ambas gerenciam o mesmo núcleo C++ incluído.

Se você já testou um servidor Zotero MCP de primeira geração, lembra do ritual: o Zotero precisava estar aberto, a API local precisava estar habilitada e cada consulta percorria sua biblioteca um registro de metadados por vez. Isso serve para uma demo. Não serve quando sua biblioteca tem 5,000 PDFs e um agente dispara vinte buscas antes de você terminar de digitar uma frase.

O novo Zotero MCP Server — @docsagent/mcp-zotero v4.0.1, lançado em 21 de setembro de 2026 — é outra máquina. Ele traz duas shells (JavaScript e Python) sobre um núcleo de busca C++ nativo residente que lê o diretório de dados do Zotero diretamente. A busca funciona sem abrir o Zotero, e bibliotecas de 10,000+ PDFs se tornam uma base de conhecimento em nível de milissegundos para Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI, Qwen Code, Cline ou qualquer outro cliente MCP.

Este é o guia da nova versão: o que mudou, como instalá-la nos dois runtimes, as 8 ferramentas que seu agente recebe e os números de benchmark para bibliotecas realmente grandes.

O que há de novo no Zotero MCP Server 4.0

Duas shells, um núcleo. O mesmo contrato de ferramentas está disponível como pacote TypeScript no npm (@docsagent/mcp-zotero) e como pacote Python no PyPI (docsagent-mcp-zotero). Escolha o runtime que sua stack já usa — as ferramentas, os esquemas, os códigos de erro e o gate de escrita são idênticos.
Não precisa iniciar o Zotero. O núcleo em C++ lê ~/Zotero/zotero.sqlite e o diretório storage/ diretamente, então a indexação e a busca continuam funcionando com o Zotero fechado — ou mesmo em uma máquina onde ele nunca foi instalado.
Um serviço residente, não um subprocesso por chamada. O núcleo roda em segundo plano em http://127.0.0.1:23120/rpc, reconstrói seu índice conforme sua biblioteca muda e permanece aquecido entre reinicializações do cliente MCP. Seu agente nunca paga o custo de uma partida a frio.
Feito para bibliotecas grandes. Busca de texto completo BM25 com índice invertido + ranking de passagens sobre 1,000+ PDFs a ~15 ms, com consumo de memória na casa das centenas de MB em vez de gigabytes.
8 ferramentas MCP (5 de leitura + 3 de escrita) com argumentos validados por esquema JSON, orçamentos de tokens, deduplicação de resultados e um gate de segurança de escrita em três camadas.
Dois transportes. stdio para clientes MCP locais; Streamable HTTP (/mcp) com verificação de origem, autenticação por API key ou OAuth 2.0 (RFC 7662) e RBAC por requisição quando você o implanta remotamente.
Um único arquivo de configuração. O ~/.docsagent/config.json é compartilhado pela shell JS, pela shell Python e pelo núcleo em C++.

Como funciona: duas shells sobre um núcleo nativo

MCP Client (Claude Code / Claude Desktop / Cursor / Codex / Gemini CLI / Qwen Code / Cline)
        │  stdio (local)   or   Streamable HTTP  /mcp  (remote)
        ▼
MCP shell  ← @docsagent/mcp-zotero  (TypeScript)  or  docsagent-mcp-zotero  (Python)
   · spec-driven tool schemas, argument validation, token budget, dedup
   · write orchestration via the Zotero local API, write safety gate, RBAC
        │  JSON-RPC 2.0 over HTTP  ({coreHost}:{httpPort}/rpc)
        ▼
DocsAgent Core  (resident C++ engine)
   · reads ~/Zotero/zotero.sqlite + storage/ directly
   · builds & serves the full-text index (BM25 + passage ranking)

A separação importa. A shell é fina — ela guarda os esquemas das ferramentas, valida os argumentos, aplica os orçamentos de tokens e nunca toca nos seus arquivos do Zotero. O núcleo faz o trabalho pesado em C++, e é por isso que o mesmo motor atende tanto o pacote do npm quanto o do PyPI com comportamento byte a byte idêntico.

Início rápido: conecte o Zotero ao seu agente de IA em 3 passos

Opção A — JavaScript / npm

# 1. start the resident search core (background service)
npx @docsagent/mcp-zotero start
npx @docsagent/mcp-zotero status    # pid / endpoint / version

Depois adicione o servidor às configurações do seu cliente MCP (Claude Desktop, Cursor, Cline, Qwen Code, …):

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "npx",
      "args": ["-y", "@docsagent/mcp-zotero"]
    }
  }
}

Opção B — Python

# 1. install the Python shell (ships the same bundled core binaries)
pip install docsagent-mcp-zotero
docsagent-mcp-zotero core start
docsagent-mcp-zotero core status

Depois registre a shell Python da mesma forma:

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "docsagent-mcp-zotero",
      "args": []
    }
  }
}

Reinicie seu cliente MCP e pergunte algo como "O que minha biblioteca Zotero diz sobre degradação de baterias em células de sódio-íon?" — o agente chama search, recebe passagens ranqueadas por BM25 com citações zotero:KEY e responde a partir dos seus PDFs em vez da web aberta.

As duas CLIs também expõem comandos de ciclo de vida do núcleo — start, stop, restart, status (o Python os executa sob um subcomando core, ou seja, docsagent-mcp-zotero core restart) — além de --transport streamable-http quando você quer servir /mcp pela rede.

As 8 ferramentas que seu agente pode chamar

Ferramenta	Tipo	O que faz
`list_sources`	leitura	Todas as fontes pesquisáveis, com capacidades e contagens de documentos. Chame esta primeiro.
`search`	leitura	Busca em toda a biblioteca por itens, anotações ou notas; profundidade `ids` / `snippets` / `full`, filtros por tags, intervalo de anos, tipo de item, autores e coleções.
`get_content`	leitura	Lê uma entrada como passagens ranqueadas pela consulta (`k`) ou texto completo com paginação por offset.
`get_metadata`	leitura	Metadados, resumo, anotações, notas e citações (BibTeX / CSL-JSON / formatadas).
`list_library`	leitura	Navegue por coleções, itens, tags, buscas salvas e notas independentes.
`import_item`	escrita	Importe PDFs locais ou resolva DOI / ISBN / arXiv IDs, com classificação automática opcional em coleções.
`add_note`	escrita	Grave uma nota em Markdown de volta em um item como nota filha do Zotero, com rollback.
`batch_modify`	escrita	Adicione ou remova coleções ou tags em massa em até 200 itens.

As ferramentas de escrita não são registradas de forma alguma a menos que você defina enableWrites: true. Mesmo assim, uma chamada não confirmada retorna uma prévia e não consome cota, as escritas confirmadas têm limite de taxa (30/hour por padrão) e qualquer batch_modify acima de 20 itens volta com requiresConfirmation. Um agente pode ler sua biblioteca o dia inteiro; ele não pode reescrevê-la em silêncio.

Desempenho: 10,000 PDFs, 42 GB, indexados em ~7 minutos

O núcleo deste servidor MCP é o mesmo motor de indexação e recuperação por trás do benchmark de busca do PapersGPT. Números de uma instalação real do Zotero:

Tamanho da biblioteca	Dados brutos	Construção do índice	Tempo médio de consulta	Memória (RSS)	Tamanho do índice
1,000 PDFs	4.2 GB	51.5 s	13.1 ms	353 MB	100 MB
10,000 PDFs	42 GB	421 s (7 m 01 s)	19.5 ms	2.21 GB	901 MB

Em uma configuração deliberadamente modesta — 4 núcleos / 8 GB de RAM — a indexação de 1,506 PDFs (4.5 GB) levou 141 segundos enquanto o processo ocupava 227 MB de memória, com recuperação média de ~15 ms. O padrão que importa:

A indexação escala de forma aproximadamente linear. Dez vezes mais PDFs, dez vezes o tempo de construção — e você paga isso uma vez por documento novo, não por pergunta.
A recuperação se mantém estável. 13 ms com 1,000 artigos, 19.5 ms com 10,000. Adicionar artigos não deixa seu agente mais lento.
A memória se mantém modesta. O descarregamento automático mantém uma biblioteca de 42 GB pesquisável dentro de cerca de 2 GB de RAM.
Tudo é offline. Nenhuma chamada à nuvem para indexar ou recuperar, então funciona em um avião, em uma rede de laboratório restrita ou sob embargo.

Por que "não precisa iniciar o Zotero" muda o fluxo de trabalho

Os servidores Zotero MCP clássicos são wrappers finos em torno da API local do Zotero (http://localhost:23119/api): sem processo do Zotero, sem respostas. Essa única dependência molda tudo — você não consegue buscar na sua biblioteca a partir de um contêiner, de uma máquina de desenvolvimento remota, de um script headless ou de uma sessão SSH; não consegue buscar enquanto o Zotero está sincronizando; e cada chamada é uma ida e volta de requisição em vez de uma consulta ao índice.

Como o núcleo do DocsAgent lê o banco de dados diretamente, a metade de leitura do fluxo de trabalho fica desacoplada do aplicativo Zotero:

	Servidores Zotero MCP baseados em API	Zotero MCP Server 4.0
O Zotero precisa estar em execução para buscar	Sim	Não
Backend de busca	Chamadas à API local do Zotero	Índice nativo C++ BM25 + passagens
Latência de consulta com 10,000 PDFs	De centenas de ms a segundos	~20 ms
Runtimes	Normalmente um	JavaScript + Python
Transporte remoto / HTTP	Raro	Streamable HTTP com autenticação + RBAC
Segurança de escrita	Normalmente manual	Gate de 3 camadas + limite de taxa

Uma ressalva honesta: as escritas ainda passam pela própria API local do Zotero, para que o Zotero continue sendo a fonte da verdade da sua biblioteca. Se você quer que o agente importe PDFs, adicione notas ou reetiquete itens, o Zotero precisa estar em execução para esse passo específico. Indexação, busca e leitura nunca precisam.

Casos de uso: o que os pesquisadores realmente fazem com isso

Pesquisa dentro do editor com Claude Code ou Cursor. Escreva seu artigo e deixe o agente extrair passagens, resumos e BibTeX direto da sua própria biblioteca enquanto você digita — sem copiar e colar, sem abas do navegador.
Triagem de literatura no terminal com Codex ou Gemini CLI. "Encontre todos os artigos da minha biblioteca que relatam uma eficiência de conversão de potência acima de 20% e adicione-os à coleção Perovskite" — search seguido de batch_modify.
Leitura offline. Em um avião ou em campo, o índice responde às consultas localmente; nada precisa de rede.
Bibliotecas de grupo. Aponte zoteroGroups para as bibliotecas compartilhadas do seu laboratório e pesquise nelas junto com sua coleção pessoal.
Skills para agentes. O projeto também publica um SKILL.md portátil, então agentes que suportam skills podem aprender o fluxo de buscar e citar em vez de adivinhar os argumentos das ferramentas.

Privacidade e segurança

Seus PDFs nunca saem da sua máquina: a indexação e a recuperação são 100% locais, e nenhum documento é enviado a qualquer serviço de nuvem. Quando você habilita as escritas de forma deliberada, elas são controladas por gates, podem ser pré-visualizadas, têm limite de taxa e são reversíveis. Quando você expõe o servidor por HTTP de forma deliberada, recebe verificação de origem, autenticação por token e RBAC por requisição em vez de uma porta aberta.

Perguntas frequentes

Preciso manter o Zotero em execução para que o servidor MCP funcione?

Não — para buscar e ler. O núcleo lê seu diretório de dados do Zotero (zotero.sqlite e storage/) diretamente, então a indexação e a busca funcionam com o Zotero fechado, e até em uma máquina onde o aplicativo desktop do Zotero não está em execução. Apenas as três ferramentas de escrita (importar itens, adicionar notas e edições em massa de tags/coleções) passam pela API local do Zotero, então o Zotero precisa estar aberto para essas.

O servidor Zotero MCP suporta Python além de JavaScript?

Sim. Existem duas shells com recursos equivalentes: @docsagent/mcp-zotero no npm para usuários de JavaScript/Node e docsagent-mcp-zotero no PyPI para Python 3.10+. As duas expõem as mesmas 8 ferramentas com os mesmos esquemas, códigos de erro e gate de escrita, e ambas gerenciam o mesmo núcleo C++ incluído.

Qual o tamanho de biblioteca Zotero que ele aguenta?

Bibliotecas com milhares de PDFs são rotina: 1,000 PDFs (4.2 GB) são indexados em cerca de 52 segundos e consultados em ~13 ms; 10,000 PDFs (42 GB) são indexados em cerca de 7 minutos e consultados em ~19.5 ms. O tempo de construção do índice cresce de forma aproximadamente linear com o tamanho da biblioteca, enquanto a latência de consulta permanece praticamente constante.

Minha biblioteca Zotero é enviada para algum lugar?

Não. O núcleo constrói e serve seu índice inteiramente na sua máquina, e a busca não exige acesso à rede. Nada sobre seus artigos é enviado ao PapersGPT ou a qualquer terceiro.

O agente de IA pode modificar minha biblioteca Zotero?

Só se você permitir. As ferramentas de escrita não são registradas a menos que enableWrites esteja definido como true; chamadas não confirmadas retornam uma prévia; as escritas confirmadas têm limite de taxa (30/hour por padrão); e lotes com vários itens acima de 20 itens exigem confirmação explícita.

Quais clientes de IA são suportados?

Qualquer cliente MCP. O projeto documenta Claude Desktop, Claude Code, Cursor, Codex, Cline, Gemini CLI e Qwen Code, e oferece um transporte Streamable HTTP para clientes que se conectam remotamente em vez de via stdio.

Como isso é diferente da configuração MCP mais antiga do PapersGPT?

A configuração mais antiga era uma ponte de propósito único construída em torno da API local do Zotero. A versão 4.0 a substituiu por um núcleo de busca C++ residente, adicionou uma shell Python de primeira classe, fez a busca funcionar sem o Zotero em execução e elevou o teto realista de "algumas centenas de artigos" para 10,000+ PDFs. O texto antigo continua online como referência histórica.

Comece agora

npx @docsagent/mcp-zotero start

Esse único comando transforma sua biblioteca Zotero em uma base de conhecimento privada e ultrarrápida para o agente de IA que você já usa. As notas de configuração, os esquemas das ferramentas e a referência completa de configuração estão no repositório docsagent, e há mais contexto na página do servidor MCP.

Quer o mesmo motor dentro do próprio Zotero — chat no app, leitura em lote com AutoPilot, LLMs locais? Veja a comparação de plugins de IA para Zotero e o PapersGPT. Quem prefere o terminal também deve ler o guia do Zotero CLI.