processo-mcp
Leverages macOS Vision framework for local OCR of PDF pages, using Apple's Neural Engine for improved accuracy on photographed documents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@processo-mcp buscar por 'sentença' no último caso"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP-Processo é um servidor MCP que faz RAG local sobre processos judiciais e administrativos volumosos em PDF (PJe, SEI, escaneados) no Claude Desktop/Code.
Jogar um PDF de 2 mil páginas no chat estoura a janela de contexto e gera alucinação. Aqui o processo vira texto página a página + um índice local — e na conversa entram só os trechos relevantes de cada pergunta, sempre com citação de (arquivo, p. N) verificável no original. Um caso de 2.000 páginas custa ao chat o mesmo que um de 20.
Feito por um advogado, para uso forense real: heurística anti-rodapé-PJe, índice de peças pela árvore do processo, cronologia por data de assinatura, validação literal de citações (dígito trocado é rejeitado) e quadro de controvérsias em .docx.
⚔️ Como funciona
~/Processos/meu-caso/ ← jogue o(s) PDF(s) na pasta
│
▼
"prepara o caso" → texto página a página + OCR local (grátis)
│ portão de integridade: o que ficou ilegível?
▼
"pode indexar" → estimativa de custo → SUA confirmação → índice
│ híbrido BM25 + denso (voyage-4-large) + rerank
▼
"busca X no caso" → trechos com página exata:【arquivo — p. N】1 chunk = 1 página — a unidade natural de citação forense.
Busca por sentido ("quebra da affectio societatis" acha "perda da clientela") e por identificador ("Lei 3.208", nº CNJ completo).
Índice visual (voyage-multimodal-3): página fotográfica/ilegível continua achável pela aparência.
Incremental por hash e conteúdo: PDF novo, substituído ou re-OCRizado reindexa só o que mudou — nunca o caso inteiro.
Related MCP server: pdf-context
🛠️ As 13 ferramentas
Ferramenta | O que faz |
| pastas de |
| extração + OCR local; caso grande roda em background |
| progresso, pendências com custo, avisos de integridade |
| estimativa → confirmação obrigatória → indexação (background se grande) |
| híbrida + rerank, filtro opcional por arquivo, seção de páginas visuais |
| texto literal da página (validação de leitura) |
| abre o PDF original na página, no navegador |
| árvore de documentos reconstruída do rodapé PJe (ou do nome do arquivo) |
| peças ordenadas pela data de assinatura |
| CONFIRMADA · QUASE · DIVERGENTE · PÁGINA ERRADA · NÃO ENCONTRADA |
| tabela autor × réu em |
| memória do caso entre conversas (com backup automático) |
| opt-in: Google Document AI para o que o OCR local não leu |
🔍 OCR em cascata
Nível | Motor | Onde roda | Custo |
1º | Apple Vision (Neural Engine) | 100% local | zero |
2º | Tesseract (fallback automático) | 100% local | zero |
— | Portão de integridade — lista o que ficou ilegível ANTES de qualquer gasto | local | zero |
3º | Google Document AI ( | nuvem ⚠️ | ~US$ 1,50/1.000 pág. |
O 3º nível é sempre manual e seletivo: a ferramenta lista as candidatas e o custo exato sem enviar nada; você audita as duvidosas com abrir_pagina (foto/planta sem texto não vale envio) e autoriza só as páginas que quiser (paginas=[...]). Sem motor de OCR funcional, o preparo aborta antes de destruir a extração anterior.
💰 Custos: nada é gasto sem confirmação
Extração + OCR local: grátis, ilimitado.
Indexação (Voyage): centavos por caso (~R$ 1,70 em um processo real de 1.561 páginas). Estimativa exata antes, confirmação sua, sempre.
OCR em nuvem (opt-in): cobrado por página, prévia exata, requisição que falha não é cobrada.
Texto (e imagem das páginas visuais) vai à Voyage sob política no-train do plano pago; para material sigiloso, use billing ativo.
📦 Instalação
git clone https://github.com/fxbarros/MCP-Processo && cd MCP-Processo
uv syncPré-requisitos: uv, Tesseract com por (brew install tesseract tesseract-lang), chave Voyage AI no Keychain (keyring set voyage-ai api_key). Registro no Claude Desktop (claude_desktop_config.json):
"processos": {
"command": "uv",
"args": ["--directory", "/caminho/para/MCP-Processo", "run", "processo-mcp"]
}Instaladores prontos (Mac e Windows) em distribuicao/LEIA-ME.md.
OCR em nuvem (ocr_nuvem) — configuração opcional
Só necessário se você quiser o 3º nível da cascata (Google Document AI) para páginas que o OCR local não leu. No Windows este recurso pesa mais: sem o Vision, o Tesseract falha com mais frequência em página fotografada — mais páginas caem na lista de ilegíveis.
No Google Cloud (1 vez): crie um projeto com billing ativo, habilite a Cloud Document AI API e crie um processador em Document AI → Galeria de processadores → Digitalização de texto → Document OCR (⚠️ não use a seção "Processadores personalizados" — são outros produtos, 20× mais caros). Anote o ID do processador e a região. Depois crie uma service account com o papel Usuário da API Document AI e baixe a chave JSON.
Na máquina, dois arquivos — nunca no repositório:
mkdir -p ~/.config/processo-mcp
mv ~/Downloads/sua-chave.json ~/.config/processo-mcp/gcp-ocr.json && chmod 600 ~/.config/processo-mcp/gcp-ocr.json
echo '{"processor_id": "SEU_ID", "location": "us"}' > ~/.config/processo-mcp/docai.jsonNo Windows, os mesmos nomes em C:\Users\<voce>\.config\processo-mcp\ (é aí que o código procura; o chmod não se aplica). Caminhos alternativos via env PROCESSO_MCP_GCP_CRED e PROCESSO_MCP_DOCAI_CONFIG no bloco do config. Faltando algo, a própria ferramenta responde com a instrução exata do que falta.
Windows
O projeto roda em Windows com duas diferenças: o OCR usa só o Tesseract (o Apple Vision não existe fora do macOS — qualidade inferior em página fotografada) e o instalador distribuicao\instalar-windows.ps1 nunca foi testado em máquina real. Se preferir não usá-lo (ou se ele falhar), o passo a passo manual:
Instale o uv e o Tesseract:
winget install astral-sh.uv UB-Mannheim.TesseractOCRSe faltar o idioma português, copie por.traineddata para
C:\Program Files\Tesseract-OCR\tessdata\(a pasta exige permissão de administrador).Na pasta do projeto, rode
uv synce grave a chave Voyage no Gerenciador de Credenciais do Windows:uv run python -c "import keyring; keyring.set_password('voyage-ai','api_key','SUA-CHAVE')"Depois, limpe o comando do histórico do PowerShell (a chave fica visível nele).
Registre o mesmo bloco JSON acima em
%APPDATA%\Claude\claude_desktop_config.json, com o caminho do projeto no formato Windows (ex.:C:/Users/voce/MCP-Processo).Os casos ficam em
C:\Users\voce\Processos\— ou aponte outra pasta via"env": {"PROCESSO_MCP_PASTA": "D:/outro/caminho"}no bloco do config.
💬 Uso no dia a dia
você: prepara o caso acp-sol-nascente claude: 1.561 páginas, 69 OCR, 0 ilegíveis. Pendente de indexação: ~1,7M tokens → US$ 0,30 (~R$ 1,67). Autoriza? você: pode indexar você: o que o réu respondeu sobre a impenhorabilidade? claude: 【contestacao.pdf — p. 85】"A arrematação de bem impenhorável..." (...) você: valida essa citação antes de eu usar na réplica claude: CONFIRMADA ✓ (similaridade 1.0)
🍎 Escopo: uso local em macOS
Projeto desenvolvido e mantido para uso pessoal, estritamente local, em macOS (Apple Silicon). Sinceridade acima de tudo:
Windows/Linux: o Vision não existe fora do macOS — o OCR cai no Tesseract (qualidade inferior em página fotografada). O instalador de Windows nunca foi testado em máquina real.
Não é um servidor: transporte stdio puro, sem HTTP, sem autenticação, sem multiusuário. Cada pessoa roda a própria cópia na própria máquina.
Testado em um hardware só: MacBook Air M2 / 8 GB — lotes e limiares calibrados para esse perfil.
✅ Testes
uv run pytest92 testes, 100% offline: rodam em pasta temporária (nunca tocam ~/Processos) e não chamam nenhuma API. Cobrem as armadilhas aprendidas em caso real — rodapé PJe mascarando página escaneada, falso-sucesso de OCR (página que "leu" só o carimbo), texto nativo virado mojibake por fonte CID sem ToUnicode, roubo de rótulo na heurística de peças, dígito trocado em citação, caracteres invisíveis das atas, órfãos no índice, rebuild sem confirmação, teto de tokens por lote, redação de chave de API em mensagem de erro.
Available Tools
12 toolsabrir_paginaB
Abre o PDF original na página indicada, na tela do usuário (navegador), para conferência visual do documento.
Inputs: caso (required), arquivo (required), pagina. Returns: result
buscarA
Busca semântica + literal no caso. Cada resultado vem com arquivo e página exata — cite sempre '(arquivo, p. N)' e confira com obter_pagina antes de afirmar algo sensível. Funciona por sentido ('quebra da affectio societatis' acha 'perda da clientela') e por identificador ('Lei 3.208'). 'arquivo' (opcional) restringe a busca a um PDF do caso — útil em caso multi-volume (ex.: só na contestação).
Inputs: caso (required), query (required), top_k, rerank, +1 more. Returns: result
cronologiaA
Linha do tempo do processo: peças ordenadas pela data de assinatura do rodapé PJe. Tipos são heurísticos — confirme peças-chave com obter_pagina.
Inputs: caso (required). Returns: result
indexar_casoA
Indexa as páginas preparadas (voyage-4-large + FTS5). Com confirmar=False só mostra a estimativa de custo — NÃO gasta nada sem confirmar=True, e a confirmação deve vir do usuário, nunca ser presumida. Incremental por hash; rebuild=True refaz do zero (ex.: troca de modelo). Caso grande roda em BACKGROUND: acompanhe com status_caso (commit por PDF — nada se perde).
Inputs: caso (required), rebuild, confirmar. Returns: result
indice_pecasA
Índice das peças do processo, reconstruído do rodapé do PJe: nº do documento, tipo (heurístico — confirme peças-chave com obter_pagina), intervalo de páginas no PDF, data e assinante. Local, grátis, cacheado.
Inputs: caso (required). Returns: result
listar_casosA
Lista os casos (subpastas de ~/Processos) com status: PDFs, páginas preparadas, índice e resumo. Ponto de partida de qualquer conversa.
Inputs: no named parameters. Returns: result
obter_paginaA
Texto LITERAL e completo de uma página (como extraído/OCR). Use para verificar citações antes de afirmar — é a fonte que valida a busca. 'arquivo' aceita nome, stem ou caminho relativo mostrado na citação.
Inputs: caso (required), pagina (required), arquivo (required). Returns: result
preparar_casoA
Extrai o texto de cada PDF do caso, página página a página (OCR local nas digitalizadas — nada sai da máquina). Grátis. Caso grande roda em background: acompanhe com status_caso. Depois, indexar_caso.
Inputs: caso (required). Returns: result
quadro_controversiasA
Gera o Quadro de Controvérsias em .docx (paisagem, tabela formatada) em /relatorios/. VOCÊ faz a análise antes: cruze inicial × contestação com buscar/obter_pagina e monte as linhas com a citação de página DENTRO de cada célula. Cada linha: {tema, autor, reu, situacao} — ex.: situacao = 'controvertido' | 'sem impugnação específica' | 'incontroverso'. NUNCA inclua afirmação sem fonte (arquivo, p. N), e TODA transcrição literal entre aspas deve passar ANTES por validar_citacoes.
Inputs: caso (required), linhas (required), titulo (required), arquivo. Returns: result
resumo_casoA
Memória do caso que sobrevive entre conversas (resumo.md na pasta). Sem conteudo: lê. Com conteudo: sobrescreve (leia antes e preserve o que ainda vale; a versão anterior fica em resumo.md.bak). Atualize ao final de sessões relevantes.
Inputs: caso (required), conteudo. Returns: result
status_casoB
Estado detalhado do caso: cada PDF (preparado? quantas páginas OCR? preparação em andamento?) e o que falta indexar, com custo estimado.
Inputs: caso (required). Returns: result
validar_citacoesA
Valida transcrições LITERAIS contra o texto real das páginas — use antes de qualquer relatório/petição. Cada item: {trecho, arquivo, pagina}. Vereditos: CONFIRMADA · QUASE (usa a passagem_real devolvida) · DIVERGENTE (número/data trocado — REJEITAR) · PÁGINA ERRADA (informa onde está de verdade) · NÃO ENCONTRADA (possível invenção — reler a fonte). Só valida citação textual; paráfrase deve ser conferida com obter_pagina.
Inputs: caso (required), citacoes (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Most tools target distinct actions: preparation/extraction (preparar_caso), indexing (indexar_caso), search (buscar), verification (obter_pagina, validar_citacoes), and report generation (quadro_controversias). Only indice_pecas vs cronologia overlap somewhat, since both describe the process's pieces (index vs date-ordered timeline), but the descriptions distinguish them adequately.
All names use consistent lowercase snake_case in Portuguese with a clear domain suffix (_caso). The only deviation is mixed structure: some are verb-led (listar_casos, preparar_caso, validar_citacoes) while others are noun phrases (status_caso, cronologia, quadro_controversias), but the style remains predictable and readable.
Twelve tools map cleanly onto a coherent legal-case workflow: list → prepare (OCR) → index → search → verify → report. Each tool earns its place with no obvious redundancy or filler.
The surface covers the full research lifecycle, from PDF extraction and indexing through search, page verification, citation validation, and .docx report generation. Minor gaps exist (no explicit case creation/deletion or editing of the summary/status artifacts beyond resumo_caso), but these are workable.
Related MCP Connectors
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Related MCP Servers
- FlicenseAqualityCmaintenanceMCP server that enables semantic search over local PDF collections using local RAG, with automatic indexing of new documents.5-
- AlicenseAqualityDmaintenanceA local-first MCP server that ingests PDFs, extracts structure, and provides semantic search and sequential navigation tools for AI clients to query and learn from documents.10MIT
- AlicenseAqualityDmaintenanceFast, local PDF parsing as an MCP server with text extraction, bounding boxes, OCR, and visual citations. No cloud or API key required.5MIT
- AlicenseBqualityAmaintenanceLocal-first MCP server that transforms civil case PDFs into queryable cases with structural provenance, evidence IDs, and page-level verification for drafting and factual review.22Apache 2.0