Zotero Local MCP Bridge
Use um endpoint MCP hospedado por plugin do Zotero para permitir que agentes locais gerenciem uma biblioteca local do Zotero com segurança.
Documentação
Zotero Local MCP Bridge
Use um endpoint MCP hospedado por plugin do Zotero para permitir que agentes locais gerenciem uma biblioteca Zotero local com segurança.
AGPL-3.0-or-later · Versão do plugin 0.1.60 · Zotero 9.x · MCP hospedado por plugin · Acesso local via loopback
简体中文 · English
O que faz · O que não faz · Escopo · Como funciona · Início rápido · Exemplos · Apoie o autor · Licença
✨ O que faz
O Zotero Local MCP Bridge permite que agentes com capacidade MCP gerenciem uma biblioteca Zotero local por meio do próprio Zotero. Não é um script de banco de dados que ignora o Zotero. É um ponto de entrada MCP local executado dentro do plugin do Zotero.
| Área | Capacidade |
|---|---|
| 📚 Itens e coleções | Ler, pesquisar, criar e editar itens; verificar em lote se registros DOI já existem; gerenciar em lote a associação em coleções de nível superior ou subcoleções |
| 📎 Anexos | Adicionar, mover, renomear e inspecionar anexos; importar arquivos PDF/EPUB únicos ou múltiplos e acionar o reconhecimento de metadados integrado do Zotero e a lógica de renomeação de anexos |
| 📝 Anotações e citações | Ler, criar e atualizar anotações PDF suportadas; formatar citações e bibliografias por meio do Zotero |
| 🔁 Importação e exportação | Importar e exportar BibTeX, RIS e CSL JSON |
| 🔎 Pesquisa | Usar fluxos de pesquisa básica, pesquisa avançada e leitura/atualização de pesquisas salvas |
| 🛡️ Fluxo de segurança | Impor dry-run para todas as gravações; suportar aprovação, auditoria, backup em nível de arquivo e desfazer |
| 🧩 Duplicatas | Encontrar duplicatas e executar fluxos controlados de mesclagem de duplicatas |
[!NOTE] As gravações não são executadas imediatamente. O agente primeiro recebe um plano de dry-run, avisos, alvos afetados e dados de confirmação. Em modos de aprovação, a execução deve aguardar a aprovação do usuário.
🚫 O que não faz
| Não suportado | Motivo |
|---|---|
| Gerenciar bibliotecas Zotero online | Este projeto não grava por meio da API Web do Zotero nem gerencia contas Zotero remotas |
Usar ZOTERO_API_KEY | Este projeto não solicita, lê ou armazena uma chave de API do Zotero |
Gravar diretamente em zotero.sqlite | As alterações devem passar pelas APIs internas do Zotero |
| Expor eval arbitrário de JavaScript | O gerenciamento comum deve vir da tabela de comandos do plugin |
| Gerenciar bibliotecas de grupo | O escopo público atual cobre apenas bibliotecas de usuário locais |
| Exclusão permanente ou esvaziar lixeira | Os fluxos atuais de exclusão usam a lixeira do Zotero ou mesclagem controlada, não apagamento irrecuperável |
| Excluir diretamente arquivos de anexo existentes | As operações de arquivos de anexo devem respeitar os limites de backup/desfazer e segurança |
📍 Escopo
Este plugin foi projetado para o Zotero Desktop e um cliente MCP local na mesma máquina. O endpoint MCP é registrado no servidor conector local do Zotero e usa apenas acesso local via loopback.
| Item | Configuração atual |
|---|---|
| Local de execução | Dentro do plugin do Zotero |
| Endpoint | http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp |
| Escopo da biblioteca | Biblioteca de usuário local |
| Caminho de gravação | APIs internas do Zotero |
| Modelo de rede | Loopback local, sem gravações em nuvem |
| Auditoria e backup | Devem permanecer fora do perfil do Zotero, do diretório de dados do Zotero, da raiz de anexos vinculados e dos diretórios de anexos |
O modo de execução é configurado em Settings -> Zotero Local MCP Bridge:
| Modo | Comportamento |
|---|---|
readonly | Bloqueia todas as gravações |
askforapprove | O agente solicita aprovação do usuário após o dry-run |
yolo | Gravações comuns podem ser executadas automaticamente quando o plano permitir; operações de alto risco ou futuras operações irrecuperáveis ainda exigem confirmação explícita |
⚙️ Como funciona
MCP-capable agent
-> MCP tool call
-> Zotero local connector server
-> Zotero Local MCP Bridge plugin endpoint
-> plugin command table
-> Zotero internal API
O endpoint MCP é hospedado dentro do plugin do Zotero:
http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp
Não há processo MCP separado de Node, Python ou sidecar para iniciar. Iniciar o Zotero inicia o endpoint do plugin. Fechar o Zotero o interrompe. A versão de lançamento expõe ferramentas MCP, não o antigo endpoint de comando privado.
Codex e Claude Code podem se conectar diretamente ao endpoint MCP Streamable HTTP. OpenCode e outros clientes com suporte a stdio, mas sem suporte a Streamable HTTP, podem usar o adaptador stdio autônomo. O adaptador é executado no lado do agente, permanece fora do XPI e nunca toca no banco de dados do Zotero.
🚀 Início rápido
1. Baixar Arquivos de Lançamento
Baixe em GitHub Releases:
| Arquivo | Finalidade |
|---|---|
zotero-local-mcp-bridge.xpi | Plugin do Zotero |
zotero-local-mcp-bridge-<version>.mcpb | Pacote MCP do Claude Desktop para macOS e Windows |
| Skill em inglês | Para agentes que falam inglês |
| Skill em chinês | Para agentes que falam chinês |
2. Instalar o Plugin do Zotero
Abra o gerenciador de plugins do Zotero:
Tools -> Plugins
Arraste zotero-local-mcp-bridge.xpi para a janela do gerenciador de plugins, confirme a instalação quando solicitado e reinicie o Zotero.
3. Escolher o Modo de Execução
Abra:
Settings -> Zotero Local MCP Bridge
Para o primeiro uso, comece com readonly ou askforapprove. Use yolo somente depois de entender o comportamento de dry-run, aprovação, auditoria e backup.
4. Conectar o Cliente MCP
Os agentes podem se conectar via stdio ou Streamable HTTP. Usuários do Claude Desktop no macOS ou Windows podem instalar o adaptador MCPB empacotado.
Opção A: stdio MCP
Instale o adaptador npm:
npm install -g zotero-local-mcp-bridge-stdio-adapter
Em seguida, configure o MCP stdio no seu agente:
[mcp_servers.zotero-local-mcp-bridge]
command = "zotero-local-mcp-bridge-stdio"
args = []
startup_timeout_sec = 20
tool_timeout_sec = 120
Configuração genérica de MCP stdio:
{
"mcpServers": {
"zotero-local-mcp-bridge": {
"type": "stdio",
"command": "zotero-local-mcp-bridge-stdio",
"args": []
}
}
}
Você também pode usar npx sem instalação global:
{
"mcpServers": {
"zotero-local-mcp-bridge": {
"type": "stdio",
"command": "npx",
"args": ["-y", "zotero-local-mcp-bridge-stdio-adapter"]
}
}
}
O adaptador stdio é uma camada de compatibilidade iniciada pela sessão do agente. Ele encaminha solicitações MCP stdio para o endpoint MCP HTTP do plugin do Zotero. Não é o próprio plugin do Zotero e não inicia com o Zotero.
Antes de editar uma configuração de agente, verifique o plugin instalado e o endpoint MCP:
zotero-local-mcp-bridge-stdio doctor
O comando de verificação única checa a inicialização do MCP e a descoberta de ferramentas, depois imprime a versão do plugin detectada, a contagem de ferramentas e as configurações prontas para copiar do Codex, Claude Code e OpenCode. Ele não modifica as configurações do agente.
Consulte a matriz de compatibilidade de clientes para conhecer as limitações do Codex, Claude Code, OpenCode, Claude Desktop e do ChatGPT atual.
Opção B: HTTP MCP
Se o seu agente suporta Streamable HTTP / HTTP MCP, você pode pular o pacote npm e conectar-se diretamente ao endpoint do plugin do Zotero:
http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp
Exemplo com Codex:
[mcp_servers.zotero-local-mcp-bridge]
url = "http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp"
startup_timeout_sec = 10
tool_timeout_sec = 120
Exemplo com Claude Code:
claude mcp add --transport http zotero-local-mcp-bridge http://127.0.0.1:23119/zotero-local-mcp-bridge/mcp
Opção C: Claude Desktop MCPB
Instale zotero-local-mcp-bridge-<version>.mcpb no Claude Desktop no macOS ou Windows. O MCPB contém o adaptador de compatibilidade stdio, não o plugin do Zotero; instale o XPI primeiro e mantenha o Zotero aberto. Consulte Configuração do Claude Desktop.
5. Instalar a Skill Correspondente
| Idioma | Skill |
|---|---|
| Inglês | skills/zotero-local-mcp-bridge/SKILL.md |
| Chinês | skills/zotero-local-mcp-bridge-zh-cn/SKILL.md |
Diga ao agente para usar o Zotero por meio do Zotero Local MCP Bridge. Quando a aprovação for necessária, o agente deve descrever brevemente a operação pendente e aguardar a aprovação do usuário.
6. Executar a Primeira Consulta Somente Leitura
Pergunte ao agente:
List my Zotero collection tree without making changes.
O agente deve chamar zotero_collection_get_tree com libraryScope=local-user. Esta consulta não requer aprovação de gravação.
🧪 Exemplos
| Peça ao agente para | Comportamento esperado |
|---|---|
| Listar minha árvore de coleções do Zotero | Consulta somente leitura, sem confirmação de gravação |
| Verificar quais valores de DOI já existem na minha biblioteca | Executar uma consulta em lote e retornar itens correspondentes, chaves de item reutilizáveis e valores de DOI sem correspondência |
| Adicionar estes itens existentes a "Current Project / Reading Queue" | Usar um dry-run, uma aprovação quando necessário e uma gravação em lote, ignorando membros existentes |
| Criar uma subcoleção "Reading Queue" sob "Current Project" | Fazer dry-run primeiro, depois pedir aprovação |
| Adicionar este anexo PDF a este item | Resolver o item e o caminho do arquivo, depois fazer dry-run da operação de anexo |
| Importar este PDF e recuperar metadados automaticamente | Fazer dry-run primeiro, depois usar o fluxo de reconhecimento integrado do Zotero para criar o item pai e renomear o anexo de acordo com as preferências |
| Importar estes PDFs e recuperar metadados automaticamente | Usar a ferramenta de reconhecimento em lote com um dry-run, uma aprovação e uma execução |
| Exportar itens selecionados como BibTeX | Exportação somente leitura, sem confirmação de gravação |
| Formatar uma bibliografia com um estilo escolhido | Usar o formatador de citações do Zotero |
No modo de aprovação, uma única operação de gravação deve interagir por meio do agente assim:
I am about to create a subcollection named "Reading Queue" under "Current Project". Approve execution?
Múltiplas operações pendentes usam uma tabela numerada, para que o usuário possa aprovar todas as operações ou aprovar apenas números selecionados:
The following operations need approval:
| No. | Operation |
|---:|---|
| 1 | Move subcollection "Temporary" under "Old Project" to Zotero trash |
| 2 | Merge duplicate items "Smith 2024" and "Smith 2024 copy" |
| 3 | Add "Zotero MCP design notes" to "Current Project / Reading Queue" |
O usuário pode responder "aprovar todas", ou responder "aprovar 1 e 3, rejeitar 2".
Se este projeto ajuda no seu fluxo de trabalho, considere dar uma estrela no repositório ou abrir uma issue focada com feedback reproduzível.
❤️ Apoie o Autor
📄 Licença
O Zotero Local MCP Bridge é licenciado sob AGPL-3.0-or-later. Consulte LICENSE.