MCP-PJe-TJMA

<h1 align="center"> <img alt="MCP PJe-TJMA 1º e 2º Graus" src="https://raw.githubusercontent.com/fxbarros/MCP-PJe-TJMA/main/docs/assets/banner.svg?sanitize=true"> <br> <small>Expedientes, prazos e autos do PJe do TJ-MA 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 do Tribunal de Justiça do Maranhão (PJe-TJMA) — 1º e 2º graus — em linguagem natural. Derivado do MCP PJe-TJPI, com as duas instâncias do TJMA atendidas pelo mesmo servidor.

🏛️ As duas instâncias

Grau	URL	client_id (SSO PDPJ)
1g (varas)	https://pje.tjma.jus.br/pje	pje-tjma-1g
2g (câmaras/turmas)	https://pje2.tjma.jus.br/pje2g	pje-tjma-2g

Toda ferramenta aceita o parâmetro grau ("1" padrão, "2" para o 2º grau — aceita também "segundo", "apelação", "câmara"...). 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-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 TJMA/ 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").

📂 Onde os arquivos são salvos

~/Library/Mobile Documents/com~apple~CloudDocs/
├── Processos TJMA 1 Grau/{cnj}/    # autos, documentos e peças do 1º grau
├── Processos TJMA 2 Grau/{cnj}/    # idem, 2º grau (mesmo CNJ ≠ mesma pasta!)
└── Modelos TJMA/                   # 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-tjma
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-TJPI neste Mac, pule esta etapa — o servidor reaproveita as credenciais PDPJ do service 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-tjma) — nunca em arquivo.

3) Registre o MCP no Claude Desktop

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

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

4) Reinicie o Claude Desktop

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

💬 Exemplos de uso

Tenho expedientes pendentes no TJMA?

Quais meus prazos urgentes no 2º grau do TJMA?

Consulte o processo 0000000-00.0000.8.10.0001

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

Busca processos pela minha OAB no TJMA

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-tjma/
├── README.md
├── requirements.txt
├── setup_credenciais.py     # setup inicial (opcional se já usa o MCP TJPI)
└── 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 TJMA/

🔒 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-TJMA. 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>