.codex-plugin— mcp server

<div align="center"> <h1>@cyanheads/courtlistener-mcp-server</h1> <p><b>Search and retrieve US court opinions, federal dockets, judge records, citation networks, and oral arguments from CourtListener's 9M+ opinion corpus via MCP. STDIO or Streamable HTTP.</b> <div>13 Tools</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

Public Hosted Server: https://courtlistener.caseyjhand.com/mcp

</div>

Tools

13 tools spanning the full CourtListener dataset — opinion search and retrieval, citation network traversal, federal docket lookup, party and attorney lookup, judge biography, judicial financial disclosures, court discovery, and oral argument search and detail:

courtlistener_search_opinions

Search the 9M+ opinion corpus. Returns opinion cluster summaries with matched text excerpts.

• Free-text queries with field syntax: caseName:, court_id:, judge:, docketNumber:, cites:(id), boolean AND / OR / NOT
• Filter by court ID, date range, publication status (Published / Unpublished / In-chambers, etc.)
• Sort by relevance score, filing date (asc/desc), or citation count
• Cursor-based pagination; up to 20 results per call
• Results include cluster_id (for courtlistener_get_opinion) and docket_id (for courtlistener_get_docket) for chaining

courtlistener_get_opinion

Fetch full text and metadata for an opinion cluster.

• A cluster groups all opinions filed in a case: majority, concurrence, dissent, per curiam
• Returns html_text and plain_text for each opinion variant; surfaces download_url when local text is absent
• Includes cites[] (outbound citation IDs), cite_count, syllabus, posture, and docket link
• Single upstream request — safe within the tight free-tier rate limit

courtlistener_get_citations

Retrieve the citation network for an opinion cluster in either direction.

• cited_by (default): opinions that cite this one — measures precedential influence and downstream adoption
• citing: opinions this one cites — reveals the authority chain the court relied on
• Optional court and date filters; cursor-based pagination; up to 20 results per call
• Results include snippet showing the excerpt around the citation reference
• Rate-limit note: the free tier (125 req/day) supports 1–2 hops on a single case; deep multi-hop traversal exhausts the daily budget quickly

courtlistener_lookup_citation

Resolve a formatted legal citation string to a cluster ID.

• Accepts standard reporter formats: "410 U.S. 113", "347 U.S. 483", "93 S. Ct. 705"
• Returns cluster ID, case name, court, date filed, all known citation strings, and the canonical form CourtListener uses
• Single upstream POST to /citation-lookup/; falls back to search when unauthenticated

courtlistener_search_dockets

Search RECAP federal court dockets.

• Query matched against case name, docket number, party names, and attorney names
• party_name filter applies in addition to (AND with) the q query — more precise than embedding party names in the query
• Returns up to 3 sample document entries per docket with is_available status
• coverage_note in every response — RECAP is crowd-sourced from PACER; completeness varies by court

courtlistener_get_docket

Fetch full docket metadata and entry list for a single federal case.

• Returns all available docket entries with document availability, page count, and RECAP file path
• entries_page_size controls how many entries are returned (1–50); large cases have hundreds
• Documents with is_available: false require a PACER account or CourtListener RECAP filing — document retrieval is not exposed

courtlistener_get_parties

Fetch all parties and attorneys of record for a RECAP federal docket.

• Returns each party's name, docket-scoped role (Plaintiff, Defendant, Petitioner, Respondent, etc.), and attorneys with contact information
• Attorney names and contact details are resolved in a single batch call per page — 2 upstream requests total per invocation
• Paginate large party lists with page and page_size (max 10); keep page_size low to stay within the free-tier rate limit
• Obtain docket IDs from courtlistener_search_dockets or courtlistener_get_docket

courtlistener_search_judges

Search judge and person records across the federal and state bench.

• Filter by appointing president's last name, court ID, or political affiliation (d/r/i/l/g/u)
• Returns person_id for chaining to courtlistener_get_judge, plus current position summary
• Court IDs from courtlistener_lookup_courts can be passed directly

courtlistener_get_judge

Fetch a judge's full biographical profile.

• Complete appointment history: all courts served, position type, appointer, nomination date, confirmation date, termination reason
• Education records with school, degree, and year
• Political affiliations with date ranges; ABA ratings; Federal Judicial Center ID for cross-referencing

courtlistener_lookup_courts

List courts with optional jurisdiction and scraper filters.

• Jurisdiction codes cover federal appellate (F), district (FD), bankruptcy (FB), state supreme (SS), state appellate (SA), tribal, and more
• in_use: true (default) restricts to courts currently scraped by CourtListener
• has_opinion_scraper filter useful for planning opinion searches — courts without scrapers have sparse coverage
• Returns id (the court_id string for use in all search and filter parameters), citation string (e.g., "9th Cir."), and jurisdiction label

courtlistener_search_oral_arguments

Search appellate oral argument audio recordings — the largest public collection of oral argument audio.

• Query matched against case name and transcribed argument text (where available)
• Filters by court, argued-after, and argued-before date
• Returns download_url (MP3), duration_seconds, panel_ids (chaining to courtlistener_get_judge), and transcript snippet

courtlistener_get_oral_argument

Fetch the full detail record for a single oral argument by audio ID.

• Returns the speech-to-text transcript when transcription has completed, plus panel_ids, duration_seconds, MP3 download_url, and the linked docket_id
• Audio IDs come from courtlistener_search_oral_arguments results
• The argument date is not on this record — take it from the search result or the linked docket

courtlistener_search_financial_disclosures

Search federal judicial financial disclosure filings for ethics and recusal research.

• Filter by judge_id (a person_id from courtlistener_search_judges) and/or filing year
• Returns per-filing category counts (investments, gifts, debts, positions, reimbursements, income), itemized gifts, and a link to the source PDF
• Line-item investments — often hundreds per filing, with coded values — are summarized as counts; the linked PDF carries the full itemization

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Pluggable auth (none, jwt, oauth)
• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

CourtListener-specific:

• Complete CourtListener REST API v4 integration — opinions, dockets, judges, courts, oral arguments, citation network
• Rate-limit-aware client: 429 responses classified by window (minute / hour / day) with actionable error messages; retry with Retry-After respect
• Cursor-based pagination throughout — consistent results across all paginated endpoints
• RECAP coverage note surfaced on every docket response — sets expectations on partial PACER mirror completeness
• Tight upstream-call budget — most tools make 1–2 calls; opinion detail and citation traversal make up to 3 (resolving the linked docket or source cluster), keeping the free tier (125 req/day) usable for multi-step research

Agent-friendly output:

• Chaining IDs on every response — cluster_id, docket_id, and person_id fields are present wherever they enable a logical follow-up call, with field-level descriptions naming which tool to pass them to
• Discriminated rate-limit errors — minute / hour / day throttle identified in structured error so agents can reason about retry timing, not just "try again later"
• Coverage caveats inline — RECAP coverage_note and oral argument transcript snippet availability explicitly signaled so agents can communicate limitations to users rather than silently omitting them

Getting started

Public Hosted Instance

A public instance is available at https://courtlistener.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "courtlistener-mcp-server": {
      "type": "streamable-http",
      "url": "https://courtlistener.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file. See CourtListener account settings to generate a free API token.

{
  "mcpServers": {
    "courtlistener-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/courtlistener-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "COURTLISTENER_API_TOKEN": "your-api-token"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "courtlistener-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/courtlistener-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "COURTLISTENER_API_TOKEN": "your-api-token"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "courtlistener-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "COURTLISTENER_API_TOKEN=your-api-token",
        "ghcr.io/cyanheads/courtlistener-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 COURTLISTENER_API_TOKEN=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.2 or higher (or Node.js v24+).
• A CourtListener API token — free account at courtlistener.com. Free tier: 5 req/min, 50 req/hr, 125 req/day. Free Law Project membership unlocks higher limits.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/courtlistener-mcp-server.git

1. Navigate into the directory:

cd courtlistener-mcp-server

1. Install dependencies:

bun install

1. Configure environment:

cp .env.example .env
# edit .env and set COURTLISTENER_API_TOKEN

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. Key environment variables:

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild

  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t courtlistener-mcp-server .
docker run --rm -e COURTLISTENER_API_TOKEN=your-token -p 3010:3010 courtlistener-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/courtlistener-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools via the barrels in src/mcp-server/tools/definitions/index.ts
• Wrap CourtListener API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.