PaperlessMCP

PaperlessMCP

Pare de organizar seus documentos manualmente. Deixe a IA fazer isso.

Você tem uma instância do Paperless-ngx. Você tem centenas (milhares?) de documentos. Você sabe que deveria etiquetá-los, definir correspondentes, organizá-los adequadamente. Mas quem tem tempo para isso?

O PaperlessMCP conecta seu Paperless-ngx a qualquer IA compatível com MCP. Agora, em vez de clicar pela interface, você apenas pergunta:

"Encontre todos os meus documentos fiscais de 2023"

"Etiquete estas 50 faturas como 'Despesa de Negócio' e defina o correspondente como 'Acme Corp'"

"Envie este recibo e descubra o que é"

"Quais documentos estou perdendo na minha pasta de seguros?"

É o Paperless-ngx com esteroides de LLM. Uma interface projetada especificamente para a IA gerenciar seus documentos enquanto você faz literalmente qualquer outra coisa.

---

O Que a IA Pode Fazer Com Seu Paperless?

Tudo. CRUD completo em cada tipo de entidade:

Você Diz	A IA Faz
"Encontre recibos da Amazon acima de R$ 100"	Pesquisa documentos com filtros
"Etiquete todas as faturas de 2024 como 'Ano Fiscal 2024'"	Atualiza em massa dezenas de documentos de uma vez
"Envie este PDF e arquive-o adequadamente"	Envia, etiqueta automaticamente, define correspondente
"Exclua todos os documentos etiquetados como 'Lixo'"	Remove com confirmação (dry-run por padrão)
"Crie uma etiqueta para registros médicos, deixe-a vermelha"	Cria etiqueta com cor
"Quem me envia mais documentos?"	Lista correspondentes por contagem de documentos
"Configure um caminho de armazenamento para documentos legais"	Cria estrutura de pastas organizada

43 ferramentas cobrindo:

• Documentos — pesquisa, envio, download, atualização, exclusão, operações em massa, reprocessamento de OCR
• Etiquetas — CRUD completo com cores, regras de correspondência e hierarquia de pais
• Correspondentes — acompanhe quem envia coisas para você
• Tipos de Documento — classifique faturas, recibos, contratos, o que for
• Caminhos de Armazenamento — organize arquivos com modelos inteligentes
• Campos Personalizados — adicione seus próprios metadados (datas, valores, URLs, etc.)

Todas as operações destrutivas exigem confirmação explícita. Operações em massa usam modo dry-run por padrão, para que a IA não possa destruir seu arquivo por acidente.

---

O PaperlessMCP é Para Você?

Sim, se:

• Você usa Paperless-ngx (auto-hospedado ou na nuvem)
• Você usa qualquer assistente de IA que fale MCP (Claude, ou qualquer outra coisa que suporte o protocolo)
• Você tem um acúmulo de documentos sem etiqueta e se sente culpado por isso
• Você prefere dizer "organize isso" a clicar em 47 botões
• Você quer consultar seus documentos em inglês simples
• Você acha que computadores deveriam trabalhar para você, não o contrário

Não, se:

• Você não usa Paperless-ngx (esta não é uma ferramenta geral de documentos)
• Você gosta de etiquetar documentos manualmente (esquisito, mas respeito)
• Você não confia IA com seus arquivos (justo; operações destrutivas exigem confirmação, e operações em massa usam dry-run por padrão)

O ponto ideal: Você tem o Paperless rodando, tem uma IA compatível com MCP e quer que eles sejam amigos.

---

Começando

Você Vai Precisar

1. Uma instância do Paperless-ngx com um token de API (Configurações → Django Admin → Tokens → Crie um para seu usuário)

2. Uma IA compatível com MCP (Claude Desktop, ou qualquer coisa que fale o protocolo)

Opção 1: Docker (Recomendado)

O caminho mais rápido de zero até conversar com seus documentos.

docker run -d \
  --name paperless-mcp \
  --restart unless-stopped \
  -e PAPERLESS_BASE_URL=https://your-paperless.example.com \
  -e PAPERLESS_API_TOKEN=your-token-here \
  -p 5000:5000 \
  -v paperless-outbox:/home/mcp/outbox \
  ghcr.io/barryw/paperlessmcp:vX.Y.Z

Pegue a versão do selo acima. O pipeline de lançamento também publica latest, mas fixar uma tag versionada dá a você uma implantação reproduzível.

Conecte seu cliente MCP ao http://localhost:5000/mcp e comece a conversar com seus documentos.

O volume paperless-outbox é onde paperless_documents_export_to_outbox grava arquivos exportados. Sem ele, as exportações ficam dentro do contêiner e nenhum outro processo consegue alcançá-las — veja Compartilhando a pasta de saída com outro servidor MCP.

Opção 2: Claude Desktop

Adicione ao seu arquivo de configuração:

SO	Caminho
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "paperless": {
      "command": "dotnet",
      "args": ["run", "--project", "/path/to/PaperlessMCP/PaperlessMCP", "--", "--stdio"],
      "env": {
        "PAPERLESS_BASE_URL": "https://your-paperless.example.com",
        "PAPERLESS_API_TOKEN": "your-token-here"
      }
    }
  }
}

Reinicie o Claude Desktop. Procure o ícone de ferramentas — o Paperless deve estar lá.

Opção 3: Claude Code

Um comando se você já estiver rodando o servidor em algum lugar:

# Connect to a running Streamable HTTP server
claude mcp add --transport http paperless http://localhost:5000/mcp

Ou rode a partir do código-fonte com stdio:

claude mcp add --transport stdio paperless \
  -e PAPERLESS_BASE_URL=https://your-paperless.example.com \
  -e PAPERLESS_API_TOKEN=your-token-here \
  -- dotnet run --project /path/to/PaperlessMCP/PaperlessMCP -- --stdio

Verifique se está lá:

claude mcp list

Opção 4: LiteLLM Proxy

O LiteLLM pode registrar o PaperlessMCP como um servidor MCP HTTP Streamable em config.yaml.

Inicie o PaperlessMCP primeiro usando Docker, Kubernetes ou código-fonte, depois adicione-o ao LiteLLM:

mcp_servers:
  paperless:
    url: "http://paperless-mcp:5000/mcp"
    transport: "http"
    description: "Paperless-ngx document management"

Use uma URL que o processo do LiteLLM consiga alcançar. No Docker Compose, defina o host como o nome do serviço PaperlessMCP daquele arquivo Compose, como paperless-mcp. Se o LiteLLM rodar diretamente no host e o PaperlessMCP publicar a porta 5000, use http://127.0.0.1:5000/mcp.

Defina transport: "http" explicitamente para o endpoint /mcp do PaperlessMCP. A configuração MCP do LiteLLM usa como padrão sse, que é o transporte errado para este endpoint.

PAPERLESS_API_TOKEN pertence ao serviço PaperlessMCP; é o token que o PaperlessMCP usa ao chamar o Paperless-ngx. O PaperlessMCP não exige token de entrada em /mcp a menos que você coloque uma camada de autenticação separada, como um proxy reverso, na frente dele.

Para armazenamento MCP baseado em banco de dados do LiteLLM, habilite o armazenamento em banco de dados no LiteLLM:

general_settings:
  store_model_in_db: true

Para configuração estática, mantenha o servidor sob a chave de nível superior mcp_servers.

Opção 5: Kubernetes

Para os entusiastas de homelab que rodam k8s. Incluímos manifestos prontos para uso com suporte a Kustomize.

# Clone and customize
git clone https://github.com/barryw/PaperlessMCP.git
cd PaperlessMCP/k8s

# Customize the checked-in manifests:
# - Set PAPERLESS_BASE_URL in secret.yaml.
# - Pin a versioned image tag in deployment.yaml.
# - The image is public, so remove imagePullSecrets unless your cluster
#   provides the referenced ghcr-secret.

# Create the API token secret (it is not managed by kustomization.yaml)
kubectl create secret generic paperless-token \
  --from-literal=token=your-api-token-here

# Deploy
kubectl apply -k .

Veja os manifestos

Inclui: Deployment, Service, Ingress, Secret de URL base e Kustomization. Ajuste ao seu gosto.

Opção 6: A Partir do Código-Fonte

Para contribuidores e curiosos:

git clone https://github.com/barryw/PaperlessMCP.git
cd PaperlessMCP
dotnet run --project PaperlessMCP             # Streamable HTTP on :5000
dotnet run --project PaperlessMCP -- --stdio  # stdio mode

Requer .NET 10 SDK.

---

A Caixa de Ferramentas Completa

43 ferramentas, organizadas pelo que elas tocam. Cada entidade suporta CRUD completo.

Documentos — o evento principal

Ferramenta	O que faz
paperless_documents_search	Encontre documentos com pesquisa de texto completo e filtros
paperless_documents_get	Obtenha um documento por ID com todos os metadados
paperless_documents_upload	Envie um documento (base64)
paperless_documents_upload_from_path	Envie a partir de um caminho de arquivo
paperless_documents_update	Atualize título, etiquetas, correspondente, etc.
paperless_documents_delete	Exclua um documento (requer confirmação)
paperless_documents_bulk_update	Atualize vários documentos de uma vez
paperless_documents_download	Obtenha URLs de download, pré-visualização e miniatura; opcionalmente, incorpore arquivos pequenos como base64
paperless_documents_export_to_outbox	Grave o arquivo de um documento no diretório de saída compartilhado para que outra ferramenta possa anexá-lo por caminho
paperless_documents_preview	Obtenha URL de pré-visualização
paperless_documents_thumbnail	Obtenha URL de miniatura
paperless_documents_reprocess	Reexecute OCR em um documento

Etiquetas — organize tudo

Ferramenta	O que faz
paperless_tags_list	Liste todas as etiquetas
paperless_tags_get	Obtenha uma etiqueta por ID
paperless_tags_create	Crie uma etiqueta com cor opcional, regras de correspondência e pai
paperless_tags_update	Atualize uma etiqueta, incluindo mudar ou limpar seu pai
paperless_tags_delete	Exclua uma etiqueta
paperless_tags_bulk_delete	Exclua várias etiquetas

Correspondentes — quem envia coisas para você

Ferramenta	O que faz
paperless_correspondents_list	Liste todos os correspondentes
paperless_correspondents_get	Obtenha um correspondente por ID
paperless_correspondents_create	Crie com regras de correspondência opcionais
paperless_correspondents_update	Atualize um correspondente
paperless_correspondents_delete	Exclua um correspondente
paperless_correspondents_bulk_delete	Exclua vários correspondentes

Tipos de Documento — faturas, recibos, contratos...

Ferramenta	O que faz
paperless_document_types_list	Liste todos os tipos de documento
paperless_document_types_get	Obtenha um tipo de documento por ID
paperless_document_types_create	Crie com regras de correspondência opcionais
paperless_document_types_update	Atualize um tipo de documento
paperless_document_types_delete	Exclua um tipo de documento
paperless_document_types_bulk_delete	Exclua vários tipos de documento

Caminhos de Armazenamento — onde as coisas vivem

Ferramenta	O que faz
paperless_storage_paths_list	Liste todos os caminhos de armazenamento
paperless_storage_paths_get	Obtenha um caminho de armazenamento por ID
paperless_storage_paths_create	Crie com modelo de caminho
paperless_storage_paths_update	Atualize um caminho de armazenamento
paperless_storage_paths_delete	Exclua um caminho de armazenamento
paperless_storage_paths_bulk_delete	Exclua vários caminhos de armazenamento

Campos Personalizados — seus próprios metadados

Ferramenta	O que faz
paperless_custom_fields_list	Liste todas as definições de campos personalizados
paperless_custom_fields_get	Obtenha um campo personalizado por ID
paperless_custom_fields_create	Crie um campo (texto, data, número, monetário, etc.)
paperless_custom_fields_update	Atualize uma definição de campo
paperless_custom_fields_delete	Exclua um campo
paperless_custom_fields_assign	Atribua um valor de campo a um documento

Saúde — está vivo?

Ferramenta	O que faz
paperless_ping	Verifique conectividade e autenticação
paperless_capabilities	Liste os recursos suportados

---

Configuração

Variáveis de ambiente. Só isso. Sem arquivos de configuração para gerenciar.

Variável	Obrigatória	Padrão	Descrição
PAPERLESS_BASE_URL	Sim	—	Sua URL do Paperless-ngx
PAPERLESS_API_TOKEN	Sim	—	Token de API para autenticação
MCP_PORT		5000	Porta para o modo HTTP Streamable
MCP_RELAX_ACCEPT_HEADER		false	Normalize cabeçalhos /mcp POST Accept para clientes que não conseguem enviar ambos os tipos de mídia Streamable HTTP
MAX_PAGE_SIZE		100	Limite superior para requisições paginadas ao Paperless-ngx feitas por este servidor
HTTP_TIMEOUT_SECONDS		30	Tempo limite para requisições ao Paperless-ngx. Aumente se pesquisas grandes de texto completo expirarem
PAPERLESS_OUTBOX_DIR		/home/mcp/outbox	Diretório onde paperless_documents_export_to_outbox grava. Monte-o como um volume compartilhado ou as exportações ficarão inacessíveis fora do contêiner

Aliases suportados: PAPERLESS_URL e PAPERLESS_TOKEN também funcionam se for seu estilo, e OUTBOX_DIR é aceito para PAPERLESS_OUTBOX_DIR.

Compartilhando a pasta de saída com outro servidor MCP

paperless_documents_export_to_outbox baixa um documento no lado do servidor e o grava em PAPERLESS_OUTBOX_DIR, retornando {path, filename, mime_type, size_bytes}. O ponto é que os bytes nunca passam pelo contexto do modelo: outra ferramenta (um servidor de e-mail que anexa arquivos por caminho, por exemplo) lê o arquivo diretamente.

Isso só funciona se ambos os contêineres enxergarem o mesmo diretório. Monte um volume em ambos e certifique-se de que o caminho que o outro servidor recebe para ler corresponde ao caminho que ele enxerga:

services:
  paperless-mcp:
    image: ghcr.io/barryw/paperlessmcp:vX.Y.Z
    environment:
      PAPERLESS_BASE_URL: https://your-paperless.example.com
      PAPERLESS_API_TOKEN: your-token-here
      PAPERLESS_OUTBOX_DIR: /home/mcp/outbox
    ports:
      - "5000:5000"
    volumes:
      - outbox:/home/mcp/outbox

  some-other-mcp:
    image: example/other-mcp:latest
    volumes:
      - outbox:/home/mcp/outbox

volumes:
  outbox:

Duas coisas para saber antes de depender disso:

• Os nomes carregam o id do documento. Um nome derivado recebe o id inserido antes da extensão (invoice.pdf vira invoice_42.pdf), então dois documentos cujo arquivo tenha o mesmo nome não podem se sobrescrever. Reexportar o mesmo documento substitui o próprio arquivo. Um filename que você mesmo passa é usado como fornecido, então exportações repetidas sob um mesmo nome se substituem.
• A versão arquivada é nomeada como tal. Com original=false (o padrão), o Paperless serve o PDF arquivado, então a exportação é nomeada após o arquivo arquivado, e não após um original .jpg ou .docx. Passe original=true para obter o arquivo enviado sob seu próprio nome.
• As exportações aparecem completas. O download é transmitido para um arquivo temporário na caixa de saída e renomeado no lugar, então um leitor do outro lado do volume nunca captura um arquivo pela metade, e um symlink colocado no destino é substituído em vez de ser gravado através dele.
• O diretório deve ser gravável pelo usuário do contêiner. A imagem roda como root, a menos que você a sobrescreva, então as exportações caem em um bind mount de propriedade do root — se o contêiner consumidor rodar como um usuário não-root, defina PAPERLESS_OUTBOX_DIR para um diretório que ambos possam gravar, ou corrija a propriedade você mesmo. O diretório é criado na primeira exportação, e uma falha aparece lá, e não na inicialização.

Compatibilidade com LocalAI

Espera-se que clientes HTTP de Streamable enviem Accept: application/json, text/event-stream em requisições POST /mcp. Alguns clientes não conseguem configurar esse cabeçalho. Defina MCP_RELAX_ACCEPT_HEADER=true para que o PaperlessMCP normalize cabeçalhos Accept ausentes ou incompletos antes que o SDK do MCP lide com a requisição.

---

Apoie o Projeto

Se o PaperlessMCP economiza seu tempo, considere apoiar o desenvolvimento:

Cada ajuda mantém as luzes acesas e os commits fluindo.

---

Contribuindo

Sim, por favor. Usamos desenvolvimento baseado em trunk com commits convencionais.

git clone https://github.com/barryw/PaperlessMCP.git
cd PaperlessMCP
dotnet build
dotnet test

As regras:

• Commits convencionais (feat:, fix:, docs:, etc.) — versões sobem automaticamente
• Testes passam ou não há merge
• Operações destrutivas precisam de confirm=true; operações em massa usam dry-run por padrão

Veja CONTRIBUTING.md para o detalhamento completo.

---

Licença

MIT — faça o que quiser, só não me culpe.

---

Agradecimentos

• Paperless-ngx — o sistema de documentos que torna isso digno de construir
• Model Context Protocol — a cola entre IA e todo o resto
• Todos que já se sentiram culpados por seus documentos sem etiquetas