Oyez MCP

An MCP server that gives Claude — or any Model Context Protocol client — access to the Oyez archive of U.S. Supreme Court cases: case metadata, decisions with vote breakdowns, and full oral-argument transcripts you can filter down to a single Justice.

Data comes from the public Oyez API (api.oyez.org) and Oyez's search backend (beta-search.oyez.org). No account or API key is required.

Using the oyez tools, pull the Obergefell oral argument and show me only Justice Scalia's questions.

Tools

Every tool is keyed on the pair Term + docket ("2014", "14-556") — that is what search_cases returns and what the other four take. Start there.

Older cases sit in bucketed Terms — 1789-1850, 1850-1900, 1900-1940, 1940-1955 — where Oyez addresses a case by volume-us-page rather than by docket number: Brown v. Board is 1940-1955 + 347us483. The docket number search_cases prints is tried first and usually works anyway; where two cases share one, as Brown I and Brown II both do at "No. 1", the error names each address so you can pick.

Cite the Links line from get_case, don't build a URL. oyez.org serves the same single-page shell for every path under /cases/, so an address you compose yourself does not 404 when it is wrong — it answers 200 and renders an empty page.

Parameters

search_cases

• query — case name, party name, or docket number

• limit — 1–50 (default 10)

• include_people — also return matching Justices and advocates (default false)

get_case

• term — the Term year, e.g. "2014"

• docket — e.g. "14-556"

list_term_cases

• term — the year the Term began, so "2014" means OT2014 (October 2014 through June/July 2015)

• limit — 1–400 (default 60)

get_oral_argument

• term, docket — as above

• speaker — case-insensitive substring of a name; returns only that person's turns ("Scalia", "Verrilli")

• speaker_type — "justice" or "advocate"

• part — 1-based session index for arguments split across sessions (default: all)

• include_timestamps — prefix each turn with H:MM:SS

• max_chars — soft length cap, 1000–200000 (default 18000)

get_opinion_announcement

• term, docket, speaker, part, include_timestamps, max_chars — as above. No speaker_type here; part is how you pick between, say, the majority announcement and a dissent read from the bench.

A note on search: it matches case names, parties, and docket numbers. It is not a free-text topical search. "brown v board of education" and "14-556" work well; a bare topic like "abortion" only finds cases with that word in the title.

Oyez's own search index runs about a Term behind its case data (in September 2026 it had no 2025 Term case at all), so search_cases also scans the three most recent Terms' case lists by name and docket number and lists those matches first. A case decided this Term is found by its name or its docket number like any other.

Transcripts are long. A full argument can run tens of thousands of characters, so filter with speaker or speaker_type when you only need part of it, and raise max_chars deliberately rather than by habit.

Related MCP server: CourtListener MCP Server

Requirements

• Python 3.10 or newer

• An MCP client — Claude Code (CLI or the desktop app's Code tab), Claude Desktop, or anything else that speaks MCP over stdio

Install

Clone it, make a virtual environment, install two dependencies.

Windows (PowerShell)

Keep the folder somewhere outside AppData. The Windows Store build of Python redirects AppData paths, which breaks venv creation there; your home directory is fine.

git clone https://github.com/attorneynate/oyez-mcp.git
cd oyez-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt

Optional, and worth it — confirm it works end to end before registering:

.\.venv\Scripts\python.exe selftest.py

macOS / Linux

git clone https://github.com/attorneynate/oyez-mcp.git
cd oyez-mcp
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

.venv/bin/python selftest.py

selftest.py starts the server over stdio, lists its tools, and pulls a real transcript. If it prints All good, the server itself works and anything that goes wrong next is configuration.

Register it with your client

Point the client at the venv's Python and the absolute path to server.py. There is no activation step — the interpreter path is the activation.

Claude Code

Run this in a normal terminal, not inside a Claude Code session:

claude mcp add --scope user oyez -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

On Windows, spell out the absolute paths:

claude mcp add --scope user oyez -- "C:\path\to\oyez-mcp\.venv\Scripts\python.exe" "C:\path\to\oyez-mcp\server.py"

--scope user registers the server once for all your projects; drop the flag to register it in the current project only. Oyez's data spans everything, so user scope usually makes sense.

Check it with claude mcp list, then start Claude Code and run /mcp in the session — oyez should show as connected with its five tools.

Claude Desktop and other MCP clients

Add a stdio server to the client's config. For Claude Desktop that is claude_desktop_config.json, reachable from Settings → Developer → Edit Config:

{
  "mcpServers": {
    "oyez": {
      "command": "/absolute/path/to/oyez-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/oyez-mcp/server.py"]
    }
  }
}

On Windows, JSON needs the backslashes doubled:

{
  "mcpServers": {
    "oyez": {
      "command": "C:\\path\\to\\oyez-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\oyez-mcp\\server.py"]
    }
  }
}

Restart the client afterward. Neither config expands ~ or other shell shortcuts — use full absolute paths.

Example prompts

• "Using the oyez tools, pull the Obergefell oral argument and show me only Justice Scalia's questions."

• "Search Oyez for New York Times v. Sullivan and summarize the holding and the vote."

• "Get the opinion announcement for Obergefell and quote the part Roberts read from the bench."

• "List the 2014 Term cases, then give me the vote breakdown for Glossip v. Gross."

• "In the Citizens United argument, what did the advocates say about corporate personhood? Advocates only."

Troubleshooting

• Slow first start. A stdio server's first launch can exceed Claude Code's 30-second startup timeout. Raise it with the MCP_TIMEOUT environment variable, in milliseconds — MCP_TIMEOUT=60000 — before starting Claude Code.

• No module named 'mcp'. You registered a system Python instead of the venv's. Re-run claude mcp add, or fix the config, pointing at the .venv interpreter.

• "already exists at that scope" when re-adding. Remove the old entry first with claude mcp remove oyez --scope user, then add it again.

• venv creation fails on Windows with a message about redirects or junctions. The folder is under AppData; move it to a normal path and recreate the venv.

• A tool answers Not found on Oyez. The Term/docket pair is wrong. Tools return errors as readable text instead of crashing, so run search_cases and use the Term and docket it hands back.

• Missing or garbled speaker names in a transcript. Oyez's speaker attribution is thinner for older cases. That is the source data, not the server.

How it works

server.py is a single-file stdio MCP server. It queries the same endpoints oyez.org's own front end uses, then formats the JSON into Markdown for the model rather than passing raw API responses through: vote breakdowns become a table, transcripts become Speaker: text turns.

There is no database, and every tool call is a live HTTP request, with one exception: the three most recent Terms' case lists, which search_cases scans, are kept in memory for ten minutes. max_chars exists because full transcripts are big enough to matter to a context window.

Contributing

Bug reports and pull requests are welcome — see CONTRIBUTING.md.

License

MIT. See LICENSE.

Disclaimer

This uses unofficial Oyez endpoints. Oyez is a free law project, a collaboration of Cornell's Legal Information Institute, Justia, and Chicago-Kent College of Law; this server is not affiliated with it, endorsed by it, or supported by it. The endpoints can change or rate-limit without notice, so use this for research and education and be a considerate client.

Nothing here is legal advice. Oyez's case summaries are secondary sources written for a general audience — if you are citing the Court, go to the opinion.