cli-anything-zotero

CLI e servidor MCP para Zotero 7/8 — 52 ferramentas para permitir que a IA gerencie sua biblioteca de pesquisa localmente. Pesquise, importe, exporte, PDF, anotações e mais.

GitHub

132

Experimente este MCPPatrocinado

Documentação

cli-anything-zotero

Deixe a IA gerenciar sua biblioteca Zotero.

中文文档 | Português | Roadmap | TODO | Comandos

Aviso de legado MCP: v0.9.5 é a versão final com o comando zotero-mcp e o extra cli-anything-zotero[mcp]. Novos lançamentos são CLI/SDK-first. Usuários MCP existentes devem fixar pip install "cli-anything-zotero[mcp]==0.9.5" ou usar o branch legacy/mcp.

Para Não Programadores

Esta ferramenta foi projetada para ser usada por IA, não memorizada por você. Após uma instalação simples (~3 minutos), basta conversar com seu assistente de IA em linguagem simples:

"Encontre artigos sobre diabetes e doença renal na minha biblioteca Zotero"

"Importe este DOI para minha coleção CKM: 10.1038/s41586-024-07871-6"

"Exporte todos os artigos da minha coleção de tese como BibTeX"

"Encontre PDFs para itens da minha coleção de revisão que estão faltando"

Tudo o que você precisa fazer:

Siga os passos de Instalação abaixo
Diga ao seu assistente de IA (Claude Code, Cursor, etc.) o que você precisa
Pronto

O Que Ele Faz

Construído sobre CLI-Anything por HKUDS, esta ferramenta dá aos agentes de IA acesso total à sua biblioteca Zotero local por meio de uma JS Bridge — um plugin leve do Zotero que expõe um endpoint JavaScript privilegiado.

Pré-requisito: o aplicativo de desktop do Zotero deve estar em execução. Isso é intencional — automatizamos o cliente local (Connector, Local API, CLI Bridge), não um substituto de API somente em nuvem.

Principais recursos:

Pesquisa e navegação — pesquisa por palavras-chave, pesquisa em PDFs de texto completo, árvore de coleções, tags
Importação — a partir de DOI, PMID, arquivos RIS/BibTeX ou JSON
Exportação — BibTeX, CSL-JSON, RIS, CSV, citações formatadas
Gerenciamento de PDF — anexar arquivos, encontrar PDFs automaticamente online, pesquisar anotações
Operações de escrita — atualizar metadados, gerenciar tags, adicionar notas, acionar sincronização
Citações DOCX — transformar placeholders {{zotero:ITEMKEY}} em texto estático ou campos Zotero atualizáveis (veja abaixo)
Avançado — executar JS arbitrário do Zotero, busca semântica com embeddings locais, análise de IA

Todas as operações de escrita são executadas localmente por meio da JS Bridge — nenhuma chave de API ou conexão com a internet é necessária.

Citações DOCX: estáticas vs dinâmicas

Rascunhos gerados por IA devem usar placeholders como {{zotero:ITEMKEY}} ou {{zotero:KEY1,KEY2}} e, em seguida, convertê-los com os comandos docx.

Modo	Comando	Saída	Software extra
Estático (padrão para finais simples)	`docx render-citations` ou `docx cite --mode static`	Citações em texto simples + bibliografia estática	Não. Apenas `pip install` + JS Bridge + Zotero em execução (Local API).
Dinâmico (campos atualizáveis)	`docx insert-citations` ou `docx cite --mode dynamic`	Campos reais do Zotero no Word/LibreOffice + bibliografia atualizável	Sim — pilha extra necessária (veja tabela abaixo).
Automático	`docx cite --mode auto`	Escolhe dinâmico se a pilha estiver pronta, caso contrário estático	Igual ao dinâmico quando disponível

O modo dinâmico é opcional e não é instalado apenas pelo pip. Você também precisa de:

Requisito	Porquê
Zotero Desktop (em execução)	Biblioteca de origem + integração com processador de texto
Plugin CLI Bridge (`zotero-cli app install-plugin`)	Ponte local privilegiada usada na conversão
LibreOffice	Abre/salva o DOCX durante a inserção de campos
Plugin Zotero LibreOffice	Cria campos de citação/bibliografia atualizáveis

Verifique a máquina antes de confiar no modo dinâmico:

zotero-cli --json docx doctor

Se doctor relatar falta de LibreOffice / o add-in do LO / Bridge, use o modo estático (ou instale as peças que faltam). No macOS, o caminho dinâmico completo é testado de ponta a ponta; no Windows/Linux, doctor funciona, mas a abertura/salvamento automático pode ainda precisar de interação manual com o LibreOffice até ser verificado.

Uma única execução quando você não tiver certeza:

zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force

Uso CLI-Primeiro

cli-anything-zotero agora é mantido como uma ferramenta CLI/SDK-first. A interface principal é o comando de shell zotero-cli, que funciona bem para Codex, Claude Code, Cursor, scripts de shell e outros agentes que podem executar comandos de terminal.

Para usuários MCP legados, instale explicitamente a versão MCP congelada:

pip install "cli-anything-zotero[mcp]==0.9.5"

O branch legacy/mcp e a versão v0.9.5 permanecem disponíveis, mas o MCP não recebe mais manutenção de novos recursos após essa linha.

Instalação

Pré-requisitos: Python 3.10+, Zotero 7/8/9 (em execução).

Passo 1: Instale o pacote

pip install cli-anything-zotero

Isso instala o comando zotero-cli. O antigo comando cli-anything-zotero permanece como um alias de compatibilidade.

Passo 2: Instale o Plugin JS Bridge (uma vez, ambos os modos)

zotero-cli app install-plugin

A primeira instalação requer etapas manuais no Zotero:

O comando gera um arquivo .xpi e imprime seu caminho
No Zotero: Ferramentas → Plugins → ícone de engrenagem → Instalar Plugin a partir de Arquivo...
Selecione o arquivo .xpi e reinicie o Zotero

Após a primeira instalação, futuras atualizações via app install-plugin são automáticas.

Para usuários existentes que estão atualizando para o fluxo de citação DOCX dinâmico, atualize tanto o pacote Python quanto o plugin de ponte do Zotero:

python -m pip install -U cli-anything-zotero
zotero-cli app install-plugin
# restart Zotero
zotero-cli app plugin-status
zotero-cli docx doctor

Passo 3: Configure seu cliente de IA

Nenhuma configuração específica de cliente é necessária. Diga ao seu assistente de IA que zotero-cli está disponível; ele pode executar zotero-cli --help para descobrir comandos.

Verifique se funciona:

zotero-cli app ping
zotero-cli js "return Zotero.version"

Solução de Problemas

Problema	Solução
`Cannot resolve Zotero profile directory`	Inicie o Zotero pelo menos uma vez primeiro
Plugin não aparecendo	Reinicie o Zotero após instalar o `.xpi`
`endpoint_active: false`	O plugin falhou ao carregar — reinstale via interface do Zotero
Windows: `pip` não reconhecido	Feche e reabra o PowerShell após instalar o Python

Uso (Modo CLI)

Pesquisa e Navegação

zotero-cli item find "machine learning"
zotero-cli item search-fulltext "CRISPR"
zotero-cli collection tree

Importação

# Preferred agent ingest
zotero-cli --json add doi "10.1038/s41586-024-07871-6" --tag "review" --fetch-pdf
zotero-cli --json add arxiv 2602.02093 --collection COLLECTION_KEY
zotero-cli --json add file ./paper.pdf
zotero-cli --json add bibtex ./refs.bib --collection COLLECTION_KEY

# Lower-level import still available
zotero-cli import doi "10.1038/s41586-024-07871-6" --no-translator
zotero-cli --json item fetch-pdf ITEM_KEY --sources zotero,unpaywall,arxiv
zotero-cli --json collection fetch-pdfs COLLECTION_KEY --limit 20 --jsonl-progress

# DOCX one-shot citations
zotero-cli --json docx cite draft.docx --output draft-cited.docx --mode auto --force

# Audit recent write ops
zotero-cli --json audit tail --limit 20

Leitura e Exportação

zotero-cli item get ITEM_KEY
zotero-cli item find "keyword" --scope fields
zotero-cli item export ITEM_KEY --format bibtex
zotero-cli export bib --items KEY1,KEY2 --output refs.bib
zotero-cli item citation ITEM_KEY
zotero-cli item context ITEM_KEY              # LLM-ready context
zotero-cli docx inspect-citations draft.docx  # detect Zotero/EndNote/static citation fields
zotero-cli docx validate-placeholders draft.docx
zotero-cli docx render-citations draft.docx --output draft-static.docx --force
zotero-cli docx doctor
zotero-cli docx insert-citations draft.docx --output draft-zotero.docx --force

Para fluxos de trabalho DOCX gerados por IA, use placeholders vinculados ao Zotero, como {{zotero:ITEMKEY}} ou {{zotero:KEY1,KEY2}}, e então escolha o modo de saída final (detalhes e requisitos de software extra estão em Citações DOCX: estáticas vs dinâmicas):

Citações estáticas: docx render-citations substitui placeholders por texto de citação comum e anexa uma bibliografia estática. Caminho mais fácil; sem LibreOffice. Não pode ser atualizado pelo plugin de processador de texto do Zotero.
Citações dinâmicas: docx insert-citations converte placeholders em campos reais do Zotero/LibreOffice e cria ou atualiza um campo de bibliografia atualizável. Requer LibreOffice + add-in do Zotero LO + Bridge além do Zotero Desktop.

Os agentes de IA devem perguntar ao usuário qual modo eles desejam quando a solicitação for ambígua. Se o usuário quiser apenas um DOCX final simples e não tiver instalado o LibreOffice, prefira citações estáticas. Sempre execute docx doctor antes de prometer conversão dinâmica.

Protocolo recomendado para IA:

zotero-cli --json docx validate-placeholders <input.docx>
Se o usuário quiser referências editáveis / suporte a atualização:
- zotero-cli --json docx doctor
- zotero-cli --json docx insert-citations <input.docx> --output <final.docx> --force
- Se a conversão falhar, relate a camada com falha do doctor e pergunte ao usuário os próximos passos.
Se o usuário quiser saída estática ou o dinâmico não estiver disponível:
- zotero-cli --json docx render-citations <input.docx> --output <final.docx> --force

Mantenha esses arquivos apenas como artefatos de transferência:

Rascunho com placeholders (<input.docx>)
Rascunho final convertido (<final.docx>)
Nenhum DOCX intermediário deve ser exposto a menos que --debug-dir seja explicitamente solicitado.

Suporte de plataforma para este fluxo de trabalho opcional:

macOS: testado de ponta a ponta com abertura automática, conversão, salvamento e saída DOCX compatível com Word.
Windows/Linux: o CLI base funciona, e docx doctor pode relatar dependências ausentes. A abertura/salvamento automático completo do LibreOffice para citações DOCX dinâmicas ainda precisa de validação real em desktop Windows/Linux; os usuários podem precisar abrir ou salvar o documento do LibreOffice manualmente até que a automação da plataforma seja verificada.

validate-placeholders, zoterify-preflight e zoterify-probe são diagnósticos para configuração ou casos de falha. Adicione --debug-dir apenas quando quiser artefatos JSON para solução de problemas. docx prepare-zotero-import existe apenas como um comando de depuração experimental; não é um fluxo de escrita suportado após testes com Zotero 9 + LibreOffice. docx insert-citations e docx render-citations são as duas saídas suportadas para inserção de citações geradas por IA. item citation e item bibliography renderizam pré-visualizações estáticas; eles não são campos Zotero atualizáveis do Word/LibreOffice. A exportação BIB é um recurso de exportação separado e não faz parte do fluxo de escrita DOCX.

Escrita e Gerenciamento

zotero-cli item update KEY --field title="New Title"
zotero-cli item tag KEY --add "important"
zotero-cli item attach KEY ./paper.pdf
zotero-cli item find-pdf KEY
zotero-cli note add KEY --text "My note"
zotero-cli sync

Avançado

zotero-cli item search-annotations "risk"
zotero-cli item annotations KEY
zotero-cli item metrics KEY                   # NIH citation metrics
zotero-cli collection stats COLLECTION_KEY
zotero-cli js "return await Zotero.Items.getAll(1).then(i => i.length)"

Referência completa de comandos: docs/COMMANDS.md

Recursos Opcionais

Estes requerem serviços extras. Todo o resto funciona sem eles.

Busca Semântica

Qualquer endpoint /v1/embeddings compatível com OpenAI (Ollama, LM Studio, OpenAI, etc.).

zotero-cli item build-index                            # one-time
zotero-cli item semantic-search "cardiovascular risk"
zotero-cli item similar ITEM_KEY

Variável	Padrão	Descrição
`ZOTERO_EMBED_API`	`http://127.0.0.1:8080/v1/embeddings`	Endpoint da API de embeddings
`ZOTERO_EMBED_MODEL`	`nomic-embed-text`	Nome do modelo
`ZOTERO_EMBED_KEY`	(vazio)	Chave da API (se necessário)

Análise de IA

export OPENAI_API_KEY=sk-...
zotero-cli item analyze ITEM_KEY --question "What are the main findings?"

Usuários MCP Legados

O suporte MCP está congelado em v0.9.5. Para continuar usando o servidor MCP anterior, instale:

pip install "cli-anything-zotero[mcp]==0.9.5"

Você também pode usar o branch legacy/mcp para instalações a partir do código-fonte. A partir de v1.0.0, o pacote mantido instala apenas superfícies CLI/SDK e não fornece mais o comando zotero-mcp.

Projetos Relacionados

Existem várias ferramentas excelentes no ecossistema Zotero. Cada uma tem pontos fortes diferentes dependendo do seu caso de uso:

	cli-anything-zotero	zotero-mcp	zotero-cli-cc	pyzotero-cli
Abordagem	JS Bridge local	API Web + MCP	API Web + CLI	API Web + CLI
Melhor para	Local-first, controle total	Fluxos de trabalho nativos MCP	Pesquisa orientada por agentes	Scripts e automação
Operações de escrita	Local (sem chave de API)	Via API Web	Via API Web	Via API Web
Suporte MCP	Legado via v0.9.5	Sim	45 ferramentas	Não
CLI de terminal	Sim	Não	Sim	Sim
Acesso JS do Zotero	Sim	Não	Não	Não
Licença	Apache 2.0	MIT	CC BY-NC 4.0	MIT

Licença

Apache 2.0