Zotero MCP

Zotero MCP: Converse com sua Biblioteca de Pesquisa—Local ou Web—no Claude, ChatGPT e outros.

Zotero MCP conecta sua biblioteca de pesquisa do Zotero ao ChatGPT, Claude e outros assistentes de IA (por exemplo, Cherry Studio, Chorus, Cursor) por meio do Model Context Protocol. Pesquise em sua biblioteca, leia e anote artigos, adicione e organize itens e encontre pesquisas por significado.

Agentes de IA: leia docs/for-agents.md primeiro. Ele cobre qual rota usar, a configuração e os comandos em um só lugar.

✨ O que ele faz

• 🔍 Pesquise por título, autor, tag, coleção, texto completo ou significado (busca semântica com embeddings locais, OpenAI, Gemini ou Ollama)
• 📚 Leia metadados, BibTeX, texto completo e intervalos de páginas de PDFs, com imagens de páginas onde a extração de texto distorce matemática, figuras e tabelas
• 📝 Anote: destaques e caixas de área colocados nas palavras, figuras, tabelas ou equações exatas; notas; extração de anotações de PDF
• ✏️ Escreva: adicione artigos por DOI, URL, ISBN, BibTeX ou arquivo (com PDFs de acesso aberto), gerencie coleções e tags, mescle duplicatas
• 💻 Local ou web: no modo local, as leituras vêm diretamente do zotero.sqlite; as escritas vão para o Zotero 10+ em execução ou pela API web
• 🪶 Duas formas de acesso: um servidor MCP para aplicativos de chat, ou zotero-cli mais uma habilidade de agente para agentes de codificação
• 📊 Scite totais de citações e alertas de retratação (opcional)

🚀 Início rápido

1. Instale (Python 3.10+):

uv tool install zotero-mcp-server     # or: pip install zotero-mcp-server

Novo na linha de comando? Experimente o Zotero MCP Setup criado pela comunidade: um instalador GUI para macOS, scripts de um clique para Mac e Windows e um guia passo a passo.

2. Ative a API local do Zotero: no Zotero 7+, abra Configurações → Avançado e marque Permitir que outros aplicativos neste computador se comuniquem com o Zotero.

3. Conecte seu assistente:

zotero-mcp setup      # auto-configures Claude Desktop

ou adicione o servidor manualmente (Claude Desktop: claude_desktop_config.json; Claude Code: ~/.claude.json):

{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": { "ZOTERO_LOCAL": "true" }
    }
  }
}

4. Escritas (opcional): no Zotero 10+, execute zotero-mcp authorize-local uma vez e escolha Sempre Permitir. Em versões mais antigas do Zotero, adicione ZOTERO_API_KEY e ZOTERO_LIBRARY_ID para escrever pela API web.

Depois, pergunte coisas como "Encontre artigos na minha biblioteca sobre mecanismos de atenção", "Resuma as principais descobertas deste artigo" ou "Destaque as principais afirmações deste PDF".

ChatGPT, Cherry Studio, Chorus, Autohand e outros clientes: veja Começando.

Extras opcionais

A instalação base cobre pesquisa, leitura, anotações e escritas. Recursos mais pesados são extras:

Extra	O que adiciona	Comando de instalação
semantic	Busca semântica via ChromaDB, sentence-transformers, embeddings OpenAI/Gemini	pip install "zotero-mcp-server[semantic]"
pdf	Estruturas de PDF, layout de páginas e imagens de páginas (PyMuPDF), anotações EPUB	pip install "zotero-mcp-server[pdf]"
scite	Scite totais de citações e alertas de retratação (sem necessidade de conta)	pip install "zotero-mcp-server[scite]"
all	Tudo acima	pip install "zotero-mcp-server[all]"

Atualize a qualquer momento com zotero-mcp update.

🪶 Servidor MCP ou habilidade de agente?

Se seu agente tem um shell (Claude Code, Cursor, Codex, Windsurf, Gemini CLI, Amp, OpenCode …), um comando o ensina a usar o zotero-cli:

zotero-mcp install-skill

Um servidor MCP envia o esquema de cada ferramenta em cada solicitação, antes de você digitar qualquer coisa. A habilidade custa 98 tokens até o agente decidir que é relevante:

Rota	Em contexto	Pago
Servidor MCP, perfil padrão (38 ferramentas)	13.448	a cada solicitação
Habilidade de agente, apenas frontmatter	98	sempre
Habilidade de agente, corpo carregado	1.368	quando dispara

Use o servidor MCP quando seu cliente fala MCP, mas não tem shell (Claude Desktop, ChatGPT); use a habilidade quando tiver shell. Ambos compartilham uma configuração. Detalhes: CLI e habilidade de agente.

📖 Documentação

Guia	O que contém
Começando	Conectando Claude Desktop e Claude Code, ChatGPT, Cherry Studio, Chorus, Autohand e outros clientes MCP
Configuração	Variáveis de ambiente, escritas locais, modos web e híbrido, backend de leitura SQLite, busca global, extração de texto, opções de linha de comando
Busca semântica	Modelos de embedding, construção e atualização do índice
Ferramentas	Cada ferramenta MCP, grupos de ferramentas (ZOTERO_MCP_TOOLSETS), itens relacionados, extração de anotações de PDF
CLI e habilidade de agente	Referência de comandos zotero-cli, saída --json, install-skill
Docker	Imagens de contêiner e modos de execução
Solução de problemas	Problemas comuns e correções
Para agentes de IA	Um guia para um agente configurar ou usar o Zotero MCP

Site: stevenyuyy.com/zotero-mcp · Changelog

🤝 Contribuindo

Issues e pull requests são bem-vindos. Execute os testes com uv run pytest tests/. Um plano de teste de integração ao vivo, destinado a ser executado pelo Claude contra uma biblioteca real, está em docs/integration-test-plan.md.

☕ Suporte

Zotero MCP é gratuito e licenciado sob MIT.

Se ele economiza tempo para você ou seu laboratório, patrocinar ajuda a cobrir as partes menos glamourosas: casos extremos de Windows e WSL2, mudanças de esquema do Zotero, suporte a bibliotecas de grupo e a infraestrutura de busca/embedding.

Laboratórios e instituições: os níveis de $50 e $200 são destinados a serem reembolsáveis e incluem triagem prioritária para os problemas que afetam seu fluxo de trabalho.

Contribuidores

Obrigado a todos que contribuíram com código, correções e ideias para o Zotero MCP.

📄 Licença

MIT