MCP-PJe-TRF1

<h1 align="center"> <img alt="MCP PJe-TRF1 1º e 2º Graus" src="https://raw.githubusercontent.com/fxbarros/MCP-PJe-TRF1/main/docs/assets/banner.svg?sanitize=true"> <br> <small>Expedientes, prazos e autos do PJe da Justiça Federal da 1ª Região em linguagem natural — 1º e 2º graus num único servidor, sem nunca escrever no tribunal</small> </h1>

<p align="center"> <img alt="Python" src="https://img.shields.io/badge/python-3.10+-3776AB?logo=python&logoColor=white"> <img alt="Ferramentas" src="https://img.shields.io/badge/ferramentas-24-brightgreen"> <img alt="Graus" src="https://img.shields.io/badge/graus-1g%20%2B%202g-blueviolet"> <img alt="MCP" src="https://img.shields.io/badge/MCP-Claude%20Desktop-d97757"> <img alt="Login" src="https://img.shields.io/badge/login-CPF%20%2B%20senha%20%2B%20TOTP%20autom%C3%A1tico-black"> <img alt="Somente leitura" src="https://img.shields.io/badge/PJe-somente%20leitura-8b0000"> </p>

Servidor MCP que permite ao Claude Desktop consultar o Processo Judicial Eletrônico da Justiça Federal da 1ª Região (PJe-TRF1) — 1º e 2º graus — em linguagem natural. Derivado do MCP PJe-TJMA (que por sua vez deriva do MCP PJe-TJPI), com as duas instâncias do TRF1 atendidas pelo mesmo servidor.

🏛️ As duas instâncias

Grau	URL	client_id (SSO PDPJ)
1g (varas federais/JEFs)	https://pje1g.trf1.jus.br/pje	pje-trf1-1g
2g (turmas do TRF1)	https://pje2g.trf1.jus.br/pje	pje-trf1-2g

Toda ferramenta aceita o parâmetro grau ("1" padrão, "2" para o 2º grau — aceita também "segundo", "apelação", "turma", "trf"...). O singleton mantém uma sessão de Chromium por vez, chaveada por (persona, grau): trocar de grau fecha a sessão anterior e loga na outra instância.

O login é no SSO nacional do PDPJ (sso.cloud.pje.jus.br) — as mesmas credenciais CPF + senha + TOTP valem para os dois graus (e para outros tribunais). Se você já usa o MCP PJe-TJMA ou PJe-TJPI neste Mac, as credenciais do Keychain são reaproveitadas automaticamente.

✨ Funcionalidades

• 🔐 Login 100% automatizado: CPF + senha + 2FA (TOTP)
• ⚖️ 1º e 2º graus no mesmo servidor, com pastas de download separadas por grau (o mesmo nº CNJ existe nos dois graus)
• 📋 Expedientes pendentes e ⏰ alertas de prazos urgentes (3 dias)
• 🔍 6 formas de busca: nº CNJ, nome da parte, nome do advogado, CPF, CNPJ e OAB
• 📄 Listagem, leitura e download de documentos (HTML e PDF), incluindo autos completos com download em background (imune ao timeout do protocolo MCP)
• 🗂️ Histórico completo de expedientes de um processo (inclusive fechados/vencidos)
• 📝 Fluxo de produção: modelos de petição, salvamento de petições e relatórios na pasta do processo
• 🛡️ Tratamento automático do aviso da Resolução CNJ 121/2010 (processos de terceiros)

🛠️ As 24 ferramentas

Painel e prazos

Ferramenta	O que faz
expedientes_pendentes	intimações/despachos pendentes de ciência ou resposta
verificar_prazos_urgentes	expedientes com data limite em ≤ 3 dias
pendencias_processo	pendências (expedientes + prazos) de UM processo
expedientes_do_processo	histórico COMPLETO de expedientes (inclui fechados/vencidos)

Consulta e busca

Ferramenta	O que faz
consultar_processo	dados básicos do processo por nº CNJ
ultimas_movimentacoes	N últimas movimentações
relatorio_processo	relatório completo: dados, movimentações e documentos
buscar_por_nome_parte / buscar_por_nome_advogado	busca por nome
buscar_por_cpf / buscar_por_cnpj / buscar_por_oab	busca por identificador

Documentos e autos

Ferramenta	O que faz
listar_documentos	todos os documentos do processo
ler_documento	texto integral de um documento (HTML ou PDF)
ultima_decisao	teor da última decisão/sentença/despacho/ato ordinatório
ultimo_despacho	teor do último despacho (só despacho)
baixar_documento	baixa UM documento e salva na pasta do processo
baixar_processo	baixa os autos COMPLETOS (em background por padrão)
status_download	acompanha um download em andamento
preparar_processo	baixa o processo e decide a estratégia de análise

Produção de peças (grava só no SEU disco, nunca no PJe)

Ferramenta	O que faz
listar_modelos_peticao / ler_modelo_peticao	modelos em Modelos TRF1/ no iCloud
salvar_peticao_processo	salva petição (.docx) na pasta do processo
salvar_relatorio_processo	salva relatório de análise na pasta do processo

Parâmetros comuns: grau ("1"/"2") e persona ("advogado" padrão ou "procurador").

🔬 Diferenças do TRF1 em relação aos MCPs TJMA/TJPI

Descobertas na validação ao vivo (18/07/2026) que motivaram adaptações no parser:

• Sigla de classe em CamelCase (MSCiv, ApCiv), não maiúsculas puras (MS, AP) — regexes de cabeçalho aceitam [A-Za-z];
• IDs de documento com 10 dígitos (TJMA usa 8) — limites de dígitos ampliados para {6,12};
• Download nativo sem S3: o botão Download (a#navbar:downloadProcesso, com confirm()) dispara POST /pje/seam/resource/rest/download-autosdigitais/download e o servidor responde o próprio PDF na mesma requisição. O cliente intercepta esse POST via context.route, reescreve cronologia/idTipoDocumento no form e captura os bytes de uma geração só. Suporte a downloadParticionado (junta as partes com pypdf);
• O modal de download do TRF1 não tem as opções "incluir expediente/movimentos" do TJMA — os parâmetros são aceitos e ignorados.

📂 Onde os arquivos são salvos

~/Library/Mobile Documents/com~apple~CloudDocs/
├── Processos TRF1 1 Grau/{cnj}/    # autos, documentos e peças do 1º grau
├── Processos TRF1 2 Grau/{cnj}/    # idem, 2º grau (mesmo CNJ ≠ mesma pasta!)
└── Modelos TRF1/                   # modelos .docx/.md de petição/relatório

🧰 Requisitos

• macOS (credenciais no Keychain; em Linux/Windows funciona com keyring equivalente)
• Python 3.10+
• Claude Desktop instalado
• Conta ativa no PDPJ com 2FA configurado via app autenticador

📦 Instalação

1) Ambiente virtual + dependências

cd mcp-pje-trf1
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium

2) Credenciais

Se você já usa o MCP PJe-TJMA ou PJe-TJPI neste Mac, pule esta etapa — o servidor reaproveita as credenciais PDPJ dos services mcp-pje-tjma/mcp-pje-tjpi do Keychain (fallback automático).

Senão:

python3 setup_credenciais.py

O script pergunta CPF, senha PDPJ e seed TOTP e grava tudo no Keychain (service mcp-pje-trf1) — nunca em arquivo.

3) Registre o MCP no Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (ajuste os caminhos):

{
  "mcpServers": {
    "pje-trf1": {
      "command": "/Users/SEU_USUARIO/mcp-pje-trf1/venv/bin/python",
      "args": ["/Users/SEU_USUARIO/mcp-pje-trf1/src/server.py"]
    }
  }
}

4) Reinicie o Claude Desktop

Cmd+Q e abra de novo — as ferramentas devem aparecer.

💬 Exemplos de uso

Tenho expedientes pendentes na Justiça Federal?

Quais meus prazos urgentes no TRF1?

Consulte o processo 0000000-00.0000.4.01.4000

Consulte a apelação 0000000-00.0000.4.01.4000 no 2º grau

Busca processos pela minha OAB no TRF1

Liste os documentos do processo e lê a última decisão

Baixa os autos completos e prepara o processo para análise

🏗️ Estrutura do projeto

mcp-pje-trf1/
├── README.md
├── requirements.txt
├── setup_credenciais.py     # setup inicial (opcional se já usa MCP TJMA/TJPI)
├── teste_login_graus.py     # smoke test ao vivo: login + painel nos 2 graus
└── src/
    ├── server.py            # servidor MCP (24 tools, param grau em todas)
    ├── pje_client.py        # cliente Playwright (URL_BASES por grau)
    ├── cliente_singleton.py # 1 sessão viva, chaveada por (persona, grau)
    ├── pje_downloader.py    # downloads (pastas por grau, jobs em background)
    ├── minutas.py           # salvar petições/relatórios (.docx/.md/.txt)
    └── modelos.py           # leitura de modelos em Modelos TRF1/

✅ Estado da validação (18/07/2026)

Fluxo	1º grau	2º grau
Login SSO + troca de perfil	✅ ao vivo	✅ ao vivo
Painel de expedientes	✅ ao vivo (0 pendentes)	✅ ao vivo (0 pendentes)
Formulário de consulta (CNJ/nome/doc/OAB)	✅ ao vivo	✅ ao vivo
Busca por OAB	✅ ao vivo (8 processos)	✅ ao vivo (0 resultados)
Autos: partes, timeline, docs, leitura REST	✅ ao vivo	⏳ pendente (sem processo no 2g ainda)
Download nativo dos autos completos	✅ ao vivo (335 págs., 14,7 MB)	⏳ pendente

O código do 2º grau é o mesmo do 1º (só muda o host); a pendência é apenas de confirmação empírica quando houver processo lá.

🔒 Segurança

• Credenciais ficam no Keychain do macOS, nunca em arquivo
• Seed TOTP tratada como secret — não commitar nunca
• Nenhuma ação de escrita no PJe: este MCP só lê informação do tribunal — nunca protocola, peticiona ou altera nada (as ferramentas de "salvar" gravam apenas no seu disco local)
• Resolução CNJ 121/2010: consulta a processo de terceiro é registrada pelo próprio PJe e o retorno inclui o aviso

⚠️ Avisos importantes

Validade das credenciais — a senha do PDPJ expira periodicamente; ao trocar no site, rode setup_credenciais.py de novo (ou atualize o service que estiver em uso no Keychain).

Fragilidade de scraping — o projeto depende do HTML/JavaScript atual do PJe-TRF1. Se o tribunal mudar o layout: rode com PJE_HEADLESS=0 para ver onde trava, pegue os novos seletores no DevTools e atualize o pje_client.py.

Uso responsável — respeite o termo de uso do PJe; nada de scraping massivo; consultas a processos de terceiros ficam registradas — use com responsabilidade profissional.

📝 Licença e créditos

Uso pessoal e profissional, sem garantias — use por sua conta e risco, respeitando as regras do tribunal e do seu cliente. Construído por Fábio Ximenes Barros com ajuda do Claude, usando Playwright, PyOTP, Scrapling e pdfplumber.

<p align="center">_{Arte do banner: original — marca dos projetos MCP do autor.}</p>