zotero-mcp

zotero-mcp

Servidor MCP de leitura e escrita para Zotero. Um servidor MCP com suporte completo a escrita para gerenciar a biblioteca Zotero a partir de assistentes de IA.

Ele permite criar itens, gerenciar coleções, encontrar e mesclar duplicatas, e importar BibTeX de dentro do Claude Code/Desktop, ou de qualquer cliente compatível com MCP.

Usa a Zotero Web API (requer chave de API). Obtenha a chave em https://www.zotero.org/settings/keys.

Recursos

Busca e Leitura

Ferramenta	Descrição
search_items	Busca em texto completo com filtros de coleção, tipo e tags
get_item	Metadados detalhados ou exportação BibTeX para um único item
get_collections	Lista todas as coleções com hierarquia e contagem de itens
get_collection_items	Lista itens em uma coleção específica
find_duplicates	Encontra duplicatas por título/DOI, ou escaneia a biblioteca inteira
get_tags	Lista todas as tags com contagem de itens

Escrita

Ferramenta	Descrição
create_item	Cria item a partir de dados de campos
create_item_from_doi	Cria item por DOI (preenche metadados automaticamente via tradutor Zotero + CrossRef)
import_bibtex	Importa entradas BibTeX para uma coleção
update_item	Atualiza campos de item com proteção contra conflitos de versão

Coleções

Ferramenta	Descrição
create_collection	Cria uma coleção (com pai opcional)
add_to_collections	Adiciona um item a várias coleções de uma vez
remove_from_collection	Remove item da coleção (não o exclui)

Gerenciamento

Ferramenta	Descrição
merge_duplicates	Mescla duplicatas: transfere metadados, tags, coleções para o item mantido, exclui o restante
delete_item	Exclui um item

Instalação

Requer Python 3.11+ e uv.

# Clone the repo
git clone https://github.com/BirdInTheTree/zotero-mcp.git
cd zotero-mcp
uv sync

Uso

Claude Code

claude mcp add zotero \
  -e ZOTERO_API_KEY=your-key \
  -e ZOTERO_USER_ID=your-user-id \
  -- uv run --directory /path/to/zotero-mcp python -m zotero_mcp

Claude Desktop

Adicione à sua configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS):

{
  "mcpServers": {
    "zotero": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/zotero-mcp", "python", "-m", "zotero_mcp"],
      "env": {
        "ZOTERO_API_KEY": "your-key",
        "ZOTERO_USER_ID": "your-user-id"
      }
    }
  }
}

Configuração

Variável	Obrigatória	Descrição
ZOTERO_API_KEY	sim	Chave da Zotero Web API
ZOTERO_USER_ID	sim	Seu ID de usuário Zotero

Obtenha sua chave de API em https://www.zotero.org/settings/keys. Seu ID de usuário é exibido na mesma página.

Exemplos

Uma vez conectado, você pode pedir ao seu assistente de IA coisas como:

• "Pesquise no meu Zotero por artigos..."
• "Crie uma nova coleção chamada..."
• "Importe este BibTeX para minha coleção"
• "Encontre itens duplicados na minha biblioteca e mescle-os"
• "Adicione este artigo a ambas as coleções"
• "Consulte o DOI 10.1234/example e adicione-o à minha biblioteca"

Desenvolvimento

# Install with dev dependencies
uv sync --dev

# Run tests
uv run pytest tests/ -v

Licença

MIT