MCP 服务器

MCP-PJe-TJMA

Enables querying the Brazilian PJe court system for TJMA (1st and 2nd degrees) via natural language, with automated login, expedient and deadline checks, document listing and download, and case searches.

README

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

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