datajud-mcp-server

An MCP server for querying the CNJ DataJud public API — Brazil's national judicial process database — by unified CNJ process number. Unofficial; not affiliated with or endorsed by the CNJ.

Every process number is validated offline before ever touching the network, successful lookups are cached, and every replica shares one Redis-coordinated rate limit budget kept safely under the CNJ's documented cap. See docs/architecture.md for the full design and docs/adr/ for the reasoning behind each major decision.

Requirements

• Bun 1.3+ (package manager)
• Node.js 24+ (runtime)
• Docker (for Redis in local dev, and for building the production image)
• A DataJud API key — see Compliance below

Quickstart

git clone <this-repo-url>
cd datajud-mcp-server
bun install
cp .env.example .env
docker compose up -d redis

Option A — HTTP transport

bun run dev

In another terminal, call a tool over Streamable HTTP:

curl -s http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: <your-datajud-api-key>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_lawsuit_by_number",
      "arguments": { "processNumber": "0000832-35.2018.4.01.3202" }
    }
  }'

The Authorization header carries your DataJud key for that request — a bare token is accepted and normalized; APIKey <token> also works. No key is stored server-side; it's forwarded to DataJud and otherwise only ever touches Redis as part of a cache/rate-limit key, never as a value (docs/adr/0009-no-credential-persistence.md).

GET /health is a liveness check; GET /ready additionally confirms Redis is reachable.

Option B — stdio transport

DATAJUD_API_KEY=<your-datajud-api-key> bun run dev:stdio

stdio mode needs no Redis — it falls back to in-process cache and rate-limit adapters, correct for a single local user (docs/adr/0004, docs/adr/0008). Speak JSON-RPC over stdin/stdout to call the same tools as above.

Either transport should have a tools/call round-trip working in well under ten minutes from a fresh clone.

Claude Desktop (stdio)

Add to Claude Desktop's MCP config:

{
  "mcpServers": {
    "datajud": {
      "command": "node",
      "args": ["/absolute/path/to/datajud-mcp-server/src/main-stdio.ts"],
      "env": {
        "DATAJUD_API_KEY": "<your-datajud-api-key>"
      }
    }
  }
}

Tools

Tool	Network call?	Purpose
validate_process_number	no	Validate a CNJ process number offline and explain its structure. Call this first when a number's origin is uncertain.
search_lawsuit_by_number	yes	Look up a lawsuit by its unified CNJ process number. Returns one record per instance (grau) it appears in.
list_courts	no	List every court queryable through DataJud, with its alias and judiciary segment.

Full input/output schemas and the error taxonomy are documented in docs/mcp-tools.md.

Development

bun run test           # unit + integration + e2e
bun run test:coverage  # same, with coverage thresholds enforced
bun run test:live      # opt-in: hits the real DataJud API (needs DATAJUD_API_KEY), never runs in CI
bun run lint
bun run typecheck
bun run verify         # lint + typecheck + test:coverage + build — the same gate CI runs

Or run everything, app included, in Docker:

docker compose up --build

See docs/contributing.md for the branch model, commit convention, and PR checklist, and docs/deployment.md for how staging/production deploy to Coolify.

Compliance

• Unofficial client. This project is not built, reviewed, or endorsed by the CNJ.
• Rate limit. The CNJ DataJud public API is capped at 120 requests/minute per key. This server enforces a distributed token bucket under that cap by default (DATAJUD_RATE_LIMIT_PER_MINUTE, DATAJUD_RATE_LIMIT_SAFETY_FACTOR) — see the DataJud access terms for the authoritative limit.
• User-supplied key. The server never ships or embeds a DataJud API key. Get your own from the CNJ Acesso page and supply it per-request (HTTP) or via DATAJUD_API_KEY (stdio/local).
• Public metadata only. DataJud exposes public judicial process metadata (parties' names are not returned by the API itself); this server does not add, infer, or cache any additional personal data beyond what DataJud returns.

Security

See SECURITY.md for the vulnerability reporting process and what this project does (and does not) store.

License

MIT