MCP 服务器

MCP-PJe-TRF1

Enables natural language querying of Brazil's Federal Justice 1st Region electronic court system (PJe-TRF1) for both 1st and 2nd degrees, allowing users to check pending expedients, deadlines, case details, and download documents via an automated login and read-only MCP server.

README

<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>

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"><sub>Arte do banner: original — marca dos projetos MCP do autor.</sub></p>