@cyanheads/courtlistener-mcp-server

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

Overview

US court opinions, federal dockets, judge records, and oral arguments from CourtListener's 9M+ opinion corpus and its RECAP mirror of federal PACER filings. Search opinions and dockets, trace citation networks and precedent chains, look up judges and courts, and pull judicial financial disclosures from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Resources

Prompts

Related MCP server: CourtListener MCP Server

Capability reference

courtlistener_search_opinions tool

• Free-text field syntax (caseName:, court_id:, judge:, docketNumber:, cites:(id)) and boolean AND / OR / NOT; filter by court, date range, and publication status (Published / Unpublished / In-chambers, etc.)

• Sort by relevance score (default), filing date, 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

• Each cluster carries its opinions[] variants — per-variant opinion ID, type, author, outbound cites, and a CourtListener-hosted local_path copy of the source document

• snippet is the matched excerpt from the first variant that carries one; CourtListener does not mark which variant the search matched

courtlistener_get_opinion tool

• 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

• Each variant carries type_label — the same value courtlistener_search_opinions reports (lead-opinion, concurrence-opinion, dissent) — beside the stored type code, whose numeric prefix is a sort key

• Includes cites[] (outbound citation IDs), cite_count, syllabus, posture, and docket link

• Three upstream requests — the cluster, its opinion variants, and the linked docket for court and docket number — kept within the tight free-tier rate limit

courtlistener_get_citations tool

• 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; up to 20 results per call

• Pagination differs by direction: cited_by follows CourtListener's own cursor with the filters applied, so its total and its pages describe the same set; citing walks the cited-opinion list and filters each page as it goes, so a filtered page can come back empty with matches still ahead — the response distinguishes that from an exhausted network

• Rate-limit note: three upstream requests per call in either direction; the free tier supports 1–2 hops on a single case, and deep multi-hop traversal exhausts the daily budget quickly

courtlistener_lookup_citation tool

• Accepts standard reporter formats: "410 U.S. 113", "347 U.S. 483", "93 S. Ct. 705"

• Returns matches, one entry per citation CourtListener extracted from the input — pass a passage and every citation in it resolves, each with its own status (200 one case, 300 several candidates, 400 unrecognized reporter, 404 no match) and decoded status_label

• Each match carries the cases it resolved to: cluster_id, case_name, court / court_id, court_resolution, docket_id, date_filed, all known citation strings, cite_count, precedential_status, and judges

• An unresolved or ambiguous citation comes back inside matches, not as an error — only text carrying no parseable citation at all fails

• court is absent from the citation-lookup payload (the court lives on the linked docket), so it is resolved from docket_id — one extra request per distinct docket, bounded by max_court_lookups (default 4, up to 20; 0 skips court resolution). court_resolution (resolved / no_docket / lookup_failed / over_budget) says why a court is or isn't populated — only over_budget is worth retrying with a larger budget

• One upstream POST to /citation-lookup/ plus those court lookups, issued sequentially and stopped early on the first rate-limited response. The endpoint requires authentication and has no unauthenticated path

courtlistener_search_dockets tool

• 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 the docket's parties, attorneys, and firms, plus nature of suit, jurisdiction type, and the referred magistrate judge

• Returns up to 3 sample document entries per docket — a search excerpt, not the full filing list — each with is_available status, page count, and a fully-qualified RECAP storage URL when a copy is stored

• coverage_note in every response — RECAP is crowd-sourced from PACER; completeness varies by court

courtlistener_get_docket tool

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

• Returns each party's name, docket-scoped role (Plaintiff, Defendant, Petitioner, Respondent, etc.), and the attorneys of record on this docket with contact information

• Attorney roles are decoded to labels (Lead attorney, Terminated, …) alongside the raw code, with the date a relationship ended

• Attorney names and contact details are resolved from the docket's attorney roster — 2 upstream requests per invocation, plus one for each extra roster page on a docket with a large attorney list

• Paginate large party lists by passing a response's next_cursor back as cursor — this endpoint is cursor-paginated, so there is no page number to increment; page_size (max 10) is a request only, and CourtListener paginates at a fixed size that can return more parties than asked for

• Obtain docket IDs from courtlistener_search_dockets or courtlistener_get_docket

courtlistener_search_judges tool

• 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 a current_position summary — court, position type, appointer, selection method, and start date — selected as the position with no termination date, or the latest-starting one when several or none qualify

• Political affiliations and ABA ratings come back as expanded labels ("Democratic", "Well Qualified"), not the codes the political_affiliation filter takes

• Court IDs from courtlistener_lookup_courts can be passed directly

courtlistener_get_judge tool

• Position history: all courts served, position type, appointer, nomination date, confirmation date, termination reason — plus non-judicial roles, which carry no court and describe themselves in job_title and organization_name. /positions/ is cursor-walked under a page bound; a truncated notice and positionsShown/truncated fields report when a long career ran past it

• Position type, termination reason, and degree level come back decoded (position_type_label, termination_reason_label, degree_label) alongside the raw codes CourtListener's own filters take

• Birth, death, and position dates carry the precision CourtListener recorded — dob_granularity and the per-position date_start_granularity read year, month, or day, and a year-only record renders as the year rather than the stored YYYY-01-01 placeholder

• Education records with school, degree, and year

• Political affiliations with date ranges; ABA ratings; Federal Judicial Center ID for cross-referencing

courtlistener_lookup_courts tool

• Jurisdiction codes mirror CourtListener's own Court.JURISDICTIONS — federal appellate (F), federal district (FD), federal bankruptcy (FB), state supreme (S), state appellate (SA), plus the tribal, territory, and military benches. The full table is in the courtlistener://reference/courts resource

• status selects which bench to return: active (the default) only the courts CourtListener still scrapes, inactive only the historical and defunct ones, any both. Upstream filters these as disjoint sets, so any is the only value that reaches the whole list

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

• Page-number paginated at a fixed 20 rows per page — /courts/ ignores any requested page size, so there is no way to pull a larger page. Enumerating a whole bench costs one call per 20 courts against a rate-limited free tier, and the inactive bench is several times larger than the active one: status: 'any' makes the full set reachable, not cheap

• all_matching_court_ids returns the complete filtered id set from a bundled snapshot of every CourtListener court, at no request cost — covers the default bench and every jurisdiction filter. Empty (not a truncated prefix) when more than 1,000 courts match; check all_matching_court_ids_complete before reading emptiness as "no courts match"

courtlistener_search_oral_arguments tool

• Query matched against case name and transcribed argument text (where available)

• Filters by court, argued-after, and argued-before date

• Returns two MP3 links per recording — download_url at the originating court, and local_path, CourtListener's durable hosted copy — plus duration_seconds, panel_ids (chaining to courtlistener_get_judge), and transcript snippet

courtlistener_get_oral_argument tool

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

• Filter by judge_id (a person_id from courtlistener_search_judges) and/or filing year

• The year filter is applied to the fetched page only — CourtListener has no server-side year filter, so filings for that year on later pages are not included; page through with cursor (the response returns next_cursor even when the current page has no year match)

• 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

courtlistener_get_financial_disclosure tool

• Keyed by disclosure_id (from a courtlistener_search_financial_disclosures result); one upstream call returns every category inline

• Returns filing metadata, per-category counts, and the requested line-item rows — investments, debts, positions, reimbursements, non-investment and spouse income, agreements, and gifts

• Coded income/value columns are decoded to readable dollar ranges (e.g. N → $250,001 - $500,000)

• Pass categories: [...] to select specific categories; omit for all. When the full itemization is too large to inline, the response returns an outline of categories by size — re-call with categories: [...] to pull specific ones in full

courtlistener://reference/courts resource

• Static markdown reference: jurisdiction type codes, common court IDs, search type codes, the free-tier rate-limit reference, and the weekly maintenance window (Thursdays 21:00–23:59 PT)

• Rendered from the same jurisdiction code set the jurisdiction filter on courtlistener_lookup_courts validates against, so the two cannot disagree

• Compiled at build time and cached publicly for 24 hours — nothing here is tenant- or caller-specific

courtlistener_research_topic prompt

• Arguments: topic required; jurisdiction optional (e.g. "scotus", "ca9"); depth optional, "overview" (default, 3–5 key cases) or "deep" (adds citation-network traversal and judge lookup)

• Returns a single user-role message laying out a step-by-step CourtListener research workflow and a findings template (key cases, precedent trajectory, research gaps)

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

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

• Pagination matched to each endpoint's own paginator — cursor-based on the /search/-backed tools and on parties/attorneys, page-number on the courts and docket-entry lists — with continuation surfaced on every response

• RECAP coverage note surfaced on every docket search result — sets expectations on partial PACER mirror completeness

• Tight upstream-call budget — most tools make 1–2 calls; opinion detail and citation traversal make three (resolving the linked docket, or the source cluster's opinion variants), plus one per extra page of variants on a case that filed many. Citation lookup is the ceiling at five, resolving up to four distinct dockets for their courts

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.4.0 or higher (or Node.js v24+).

• A CourtListener API token — free account at courtlistener.com. CourtListener publishes free-tier limits of 5 req/min, 50 req/hr, 125 req/day; actual limits vary by token tier. Free Law Project membership unlocks higher limits.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd courtlistener-mcp-server

3. Install dependencies:

bun install

4. 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, resources, and prompts by importing them in src/index.ts and adding to the createApp({ tools, resources, prompts }) arrays

• Wrap CourtListener API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.