Metadata-Version: 2.4
Name: courtlistener-mcp
Version: 1.3.0
Summary: Official MCP server for CourtListener: search case law, dockets, judges and oral arguments, and verify legal citations, from any MCP client
Author-email: Free Law Project <info@free.law>
License-Expression: BSD-2-Clause
Project-URL: Repository, https://github.com/freelawproject/courtlistener-mcp
Project-URL: Organisation Homepage, https://free.law/
Keywords: legal,courts
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: mcp
Requires-Dist: asyncpg>=0.32.0; extra == "mcp"
Requires-Dist: eyecite>=2.6.0; extra == "mcp"
Requires-Dist: fastmcp==4.1.3; extra == "mcp"
Requires-Dist: gunicorn>=25.3.0; extra == "mcp"
Requires-Dist: jsonschema>=4.0.0; extra == "mcp"
Requires-Dist: prometheus-client>=0.20.0; extra == "mcp"
Requires-Dist: py-key-value-aio[postgresql,redis,wrappers-encryption]<0.5.0,>=0.4.4; extra == "mcp"
Requires-Dist: redis>=5.0.0; extra == "mcp"
Requires-Dist: sentry-sdk>=2.64.0; extra == "mcp"
Requires-Dist: tiktoken>=0.12.0; extra == "mcp"
Provides-Extra: dev
Requires-Dist: click>=8.0.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: types-jsonschema>=4.0.0; extra == "dev"
Requires-Dist: pre-commit>=4.5.1; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: python-dotenv>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: tox-uv>=1.29.0; extra == "dev"
Requires-Dist: unasync>=0.6.0; extra == "dev"
Requires-Dist: py-key-value-aio[disk]; extra == "dev"
Requires-Dist: asyncpg-stubs>=0.32.0; extra == "dev"
Dynamic: license-file

# CourtListener API Client

A Python client for the [CourtListener API](https://www.courtlistener.com/help/api/rest/v4), providing access to millions of legal opinions, dockets, judges, and more from [Free Law Project](https://free.law/).

> **Using an LLM?** This repo also ships the **CourtListener MCP server**, which exposes the API to any Model Context Protocol client (Claude Desktop, Cursor, etc.). See [MCP_README.md](MCP_README.md) for connection details and for running it locally. Free Law Project hosts it at [`mcp.courtlistener.com`](https://mcp.courtlistener.com/). See the [MCP documentation](https://wiki.free.law/c/courtlistener/help/api/mcp) on the wiki for setup instructions.

## Installation

```bash
pip install courtlistener-api-client
```

## Authentication

You'll need a CourtListener API token. You can get one by [creating an account](https://www.courtlistener.com/register/) and generating a token in your [profile settings](https://www.courtlistener.com/profile/api/).

Set it as an environment variable:

```bash
export COURTLISTENER_API_TOKEN="your-token-here"
```

Or pass it directly to the client:

```python
from courtlistener import CourtListener

client = CourtListener(api_token="your-token-here")
```

## Quickstart

```python
from courtlistener import CourtListener

client = CourtListener()

# Get a specific opinion by ID
opinion = client.opinions.get(1)

# Search for opinions
response = client.opinions.list(cluster__case_name="Miranda")

# Access results from the current page
for opinion in response.get_results():
    print(opinion)

# Check the total count of matching results
print(response.get_count())

# Iterate through all results across pages
response = client.dockets.list(court="scotus")
for docket in response:
    print(docket)
```

### Pagination

List queries return a `ResourceIterator` that handles pagination automatically:

```python
results = client.dockets.list(court="scotus")

# Iterate through all results across all pages
for docket in results:
    print(docket)

# Or navigate pages manually
results = client.dockets.list(court="scotus")
print(results.get_results())  # current page results

if results.has_next():
    results.next()
    print(results.get_results())  # next page results
```

## Available Endpoints

Access any endpoint as an attribute on the client. Each endpoint supports `.get(id)` and `.list(**filters)`.

| Endpoint | Description |
| --- | --- |
| `search` | Search opinions, RECAP, judges, and oral arguments |
| `dockets` | Court dockets |
| `docket_entries` | Docket entries |
| `recap_documents` | RECAP documents |
| `opinions` | Court opinions |
| `opinions_cited` | Citation relationships |
| `clusters` | Opinion clusters |
| `courts` | Court information |
| `audio` | Oral argument audio |
| `people` | Judges and other persons |
| `positions` | Judge positions |
| `parties` | Case parties |
| `attorneys` | Attorneys |
| `financial_disclosures` | Financial disclosures |
| `alerts` | User alerts |
| `docket_alerts` | Docket alerts |
| `prayers` | Pray and Pay requests |
| `tags` | User-created tags |
| `visualizations` | Visualization data |
| `schools` | Schools |
| `educations` | Judge education records |
| `political_affiliations` | Political affiliations |
| `aba_ratings` | ABA ratings |
| `fjc_integrated_database` | FJC integrated database |

See the [CourtListener API docs](https://www.courtlistener.com/api/rest-info/) for the full list and available filters.

## API usage and rate limits

`client.api_usage.get()` returns your live throttle usage per scope and rate,
daily request counts for the last 14 days, and membership status. The endpoint
has its own throttle scope, so checking usage never spends the quota being
checked and it stays reachable when you are rate limited.

```python
usage = client.api_usage.get()

for row in usage["current_usage"]:
    print(row["scope"], row["rate"], row["remaining"], row["reset_at"])

print(usage["historical_usage"]["total"])
```

## Async

`AsyncCourtListener` mirrors `CourtListener` method for method. Anything that
makes a request is awaited, iteration uses `async for`, and the client is an
async context manager.

```python
from courtlistener import AsyncCourtListener

async with AsyncCourtListener() as client:
    opinion = await client.opinions.get(1)

    results = client.dockets.list(court="scotus")
    async for docket in results:
        print(docket)
```
