Courtlistener ++ MCp Server

provides comprehensive access to legal case data, court opinions, federal statutes, and federal rulemaking documents

Documentation

CourtListener ++ MCP Server

A Model Context Protocol (MCP) server that provides LLM-friendly access to the CourtListener legal database through the official CourtListener API v4, plus United States statute lookup through the official GovInfo API and federal rulemaking document search through the official Regulations.gov API. This server enables searching and retrieving legal opinions, court cases, judges, legal documents, enacted federal statutes, and federal rulemaking documents for precise legal research and citation verification.

🎯 Purpose

The CourtListener ++ MCP Server provides comprehensive access to legal case data, court opinions, federal statutes, and federal rulemaking documents through the extensive CourtListener, GovInfo, and Regulations.gov databases. CourtListener contains millions of legal opinions from federal and state courts, GovInfo provides the United States Code, Statutes at Large, and Public and Private Laws, and Regulations.gov indexes federal rulemaking dockets, proposed rules, and final rules.

📋 Key Advantages

Comprehensive Legal Database:
- Access to millions of court opinions and legal decisions
- Federal and state court coverage
- Real-time updates from court systems
Full Text Content:
- Complete opinion text for citation verification
- Structured legal document organization
- Rich metadata including judges, courts, and dates
Statutory Research:
- Search across USC, Statutes at Large, Public/Private Laws, and Compilations
- Find USC sections, chapters, and subchapters within a title
- Retrieve statute package summaries or XML/PDF/text download links
Federal Rulemaking Research:
- Search federal rulemaking documents by keyword, agency, type, or posted date
- Retrieve full document details, optionally with attachments
Legal Research:
- Search by judge, court, case name, or content
- Verify exact legal language and precedents
- Validate legal citations and references

� Getting a CourtListener API Key

An API key is required for authenticated access to the CourtListener API. While some endpoints work without authentication, you will be severely rate-limited (anonymous users get throttled quickly).

Why You Need an API Key

Higher Rate Limits: Authenticated users get 5,000 queries per hour
Full API Access: Some endpoints require authentication
Better Performance: Avoid anonymous throttling
Usage Tracking: Monitor your API usage in your profile

How to Get Your API Key

Create an Account: Go to CourtListener Sign Up and create a free account.
Sign In: Log into your account at CourtListener Sign In.
Get Your Token: Navigate to API Help - REST while logged in. Your authorization token will be displayed on that page.
Copy Your Token: Your token will look something like: abcd1234567890efghij1234567890abcd123456
Configure the Server: Add your token to your .env file:
```
COURT_LISTENER_API_KEY=your-token-here
```

Token Authentication Format

When making API requests, the token is sent in the Authorization HTTP header:

Authorization: Token your-token-here

Important: Don't forget the word "Token" before your actual token value!

🏛️ Getting a GovInfo API Key

The statute lookup tools (statutes_*) use the GovInfo API from the U.S. Government Publishing Office and require a GOVINFO_API_KEY.

Get a free key: Sign up at api.data.gov — the same key works for api.govinfo.gov.
Configure the Server: Add the key to your .env file:
```
GOVINFO_API_KEY=your-api-data-gov-key-here
```

GovInfo requests authenticate with an X-Api-Key HTTP header. If GOVINFO_API_KEY is missing at startup, the server logs a warning and automatically disables every tool that requires it — the statutes_* tools are hidden from clients until the key is set and the server is restarted. The same startup behavior applies to COURT_LISTENER_API_KEY and the search_*, get_*, and citation_* tools. As a fallback, calling a key-required tool without its key still raises an error asking for the key to be set.

The status tool reports which tool groups are live under tools_available and which are disabled (with the missing key) under tools_disabled.

📜 Getting a Regulations.gov API Key

The federal rulemaking tools (regulations_*) use the official Regulations.gov API and require a REGULATIONS_API_KEY.

Get a free key: Sign up at api.data.gov — the same key works for api.regulations.gov.
Configure the Server: Add the key to your .env file:
```
REGULATIONS_API_KEY=your-api-data-gov-key-here
```

Regulations.gov requests authenticate with an X-Api-Key HTTP header. The same automatic startup behavior applies: if REGULATIONS_API_KEY is missing, the regulations_* tools are disabled and hidden from clients until the key is set and the server is restarted.

Note: the Regulations.gov API rejects page[size] values below 5, so regulations_search_documents enforces a page size between 5 and 250.

⚙️ Background Tasks (MCP Tasks Extension)

The server registers the MCP background tasks extension (SEP-2663). Long-running tools — citation_batch_lookup, citation_batch_lookup_citations, and statutes_get_statute_content — are marked task=True, so clients that opt in to the tasks capability can run them in the background with progress polling instead of blocking. Calls from ordinary clients still run synchronously, so nothing changes for existing integrations. FastMCP uses an in-memory task backend by default; set FASTMCP_DOCKET_URL (e.g. redis://localhost:6379/0) for a persistent, horizontally scalable deployment.

🐳 Docker Quick Start (Recommended)

The fastest way to get started is with Docker. Pre-built images are available from multiple registries.

Pull the Image

# From Docker Hub
docker pull vesha/court-listener-mcp:latest

# From GitHub Container Registry
docker pull ghcr.io/travis-prall/court-listener-mcp:latest

Run with Docker

# Quick start (minimal configuration)
docker run -d \
  --name court-listener-mcp \
  -p 8785:8785 \
  -e COURT_LISTENER_API_KEY=your-api-key-here \
  vesha/court-listener-mcp:latest

# With all configuration options
docker run -d \
  --name court-listener-mcp \
  -p 8785:8785 \
  -e COURT_LISTENER_API_KEY=your-api-key-here \
  -e COURTLISTENER_BASE_URL=https://www.courtlistener.com/api/rest/v4/ \
  -e COURTLISTENER_TIMEOUT=30 \
  -e COURTLISTENER_LOG_LEVEL=INFO \
  -e ENVIRONMENT=production \
  vesha/court-listener-mcp:latest

Run with Docker Compose

Create a .env file in your project directory:

# Required: Your CourtListener API Key
COURT_LISTENER_API_KEY=your-api-key-here

# Required for statute lookup: Your GovInfo (api.data.gov) API Key
GOVINFO_API_KEY=your-govinfo-api-key-here

# Optional: Regulations.gov federal rulemaking tools (auto-disabled if missing)
REGULATIONS_API_KEY=your-api-data-gov-key-here

# Optional: Override defaults
COURTLISTENER_LOG_LEVEL=INFO
ENVIRONMENT=production

Create a docker-compose.yml (or use the one in this repo):

services:
  court-listener-mcp:
    image: vesha/court-listener-mcp:latest
    container_name: court-listener-mcp-server
    ports:
      - "8785:8785"
    env_file:
      - .env
    environment:
      - LOG_LEVEL=INFO
      - API_BASE_URL=https://www.courtlistener.com/api/rest/v4
    restart: unless-stopped

Start the server:
```
docker-compose up -d
```
View logs:
```
docker-compose logs -f
```
Stop the server:
```
docker-compose down
```

Build Your Own Image

If you prefer to build the image locally:

# Clone the repository
git clone https://github.com/Travis-Prall/court-listener-mcp.git
cd court-listener-mcp

# Build the image
docker build -t court-listener-mcp:latest .

# Run your local build
docker run -d \
  --name court-listener-mcp \
  -p 8785:8785 \
  -e COURT_LISTENER_API_KEY=your-api-key-here \
  court-listener-mcp:latest

Connecting to the Docker Container

Once running, the MCP server is available at:

URL: http://localhost:8785/mcp/
Protocol: Streamable HTTP (FastMCP)

Example client connection:

from fastmcp import Client

async with Client("http://localhost:8785/mcp/") as client:
    # Check server status
    result = await client.call_tool("status")
    print(result)

    # Search for legal opinions
    result = await client.call_tool(
        "search_opinions", {"query": "first amendment", "court": "scotus"}
    )
    print(result)

Health Checks

The server exposes an unauthenticated liveness endpoint for load balancers, monitoring systems, and container orchestrators:

curl http://localhost:8785/health
# {"status":"healthy","service":"CourtListener ++ MCP Server","version":"0.2.1",...}

The Docker image ships with a HEALTHCHECK against this endpoint and the provided docker-compose.yml mirrors it, so docker ps and docker compose ps report container health automatically.

HTTP Deployment Notes

Following the FastMCP HTTP deployment guide, the server uses the direct HTTP server approach (mcp.run_async(transport="http")), which the guide recommends for standalone, single-instance deployments. For larger deployments, optional knobs (all environment-configurable):

Horizontal scaling: set FASTMCP_STATELESS_HTTP=true when running multiple replicas behind a load balancer (streamable HTTP sessions are per-instance, and sticky sessions are unreliable for MCP clients). Pair with FASTMCP_DOCKET_URL so the tasks backend is shared.
Host/origin protection: set FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true with explicit allow-lists (FASTMCP_HTTP_ALLOWED_HOSTS, FASTMCP_HTTP_ALLOWED_ORIGINS) when exposing a public hostname.
Long-running tools behind proxies: for tools that may exceed proxy timeouts, the guide recommends an EventStore for SSE polling; and when fronting with nginx set proxy_buffering off plus generous proxy_read_timeout (300s+) so streaming responses reach clients.

🛠️ Available MCP Tools

The CourtListener ++ MCP Server provides these production-ready tools (see app/README.md for full details and parameters):

Opinion & Case Search:
- search_opinions — Search legal opinions and court decisions
- search_dockets — Search court cases and dockets
- search_dockets_with_documents — Search dockets with nested documents
- search_recap_documents — Search RECAP filing documents
- search_audio — Search oral argument audio
- search_people — Search judges and legal professionals
Entity Retrieval:
- get_opinion, get_docket, get_audio, get_court, get_person, get_cluster
Citation Tools (CourtListener API + citeurl):
- citation_lookup_citation — Find the opinion a citation references (API key required)
- citation_batch_lookup_citations — Look up multiple citations in one request (API key required)
- citation_batch_lookup — Batch citation lookup with details (API key required)
- citation_get_citations — Look up citations found in a text block (API key required)
- citation_get_citation_details — Detailed information for a citation ID (API key required)
- citation_enhanced_citation_lookup — Citeurl parsing combined with CourtListener data (API key optional)
- citation_parse_citation / citation_parse_citation_with_citeurl — Parse citations offline with citeurl
- citation_validate_citation / citation_verify_citation_format — Validate citation format offline
- citation_extract_citations_from_text — Extract all citations from a block of text (offline)
Statute Tools (GovInfo API — GOVINFO_API_KEY required):
- statutes_search_statutes — Search across USC, Statutes at Large, Public/Private Laws, and Compilations
- statutes_get_uscode_title — Find USC sections, chapters, and subchapters within a title
- statutes_get_statute_content — Retrieve package/granule summaries or XML/PDF/text download links
- statutes_list_statute_collections — List available statute collections (no API call)
Regulations.gov Tools (Federal Rulemaking — REGULATIONS_API_KEY required):
- regulations_search_documents — Search federal rulemaking documents by keyword, agency, type, or posted date
- regulations_get_document — Get full document details, optionally with attachments

See app/README.md for a full reference of all tools, parameters, and usage examples.

📦 Local Installation (Alternative)

If you prefer to run without Docker:

Prerequisites

Python 3.14+
uv for dependency management
Internet connection for CourtListener API access

Install with uv

# Clone the repository
git clone https://github.com/Travis-Prall/court-listener-mcp.git
cd court-listener-mcp

# Install dependencies
uv sync

# Activate the environment (optional)
uv shell

Environment Configuration

Create a .env file in the project root (see example.env for all options):

# Required
COURT_LISTENER_API_KEY=your-api-key-here

# Required for statute lookup tools
GOVINFO_API_KEY=your-api-data-gov-key-here

# Optional: Regulations.gov federal rulemaking tools (auto-disabled if missing)
REGULATIONS_API_KEY=your-api-data-gov-key-here

# Optional (defaults shown)
COURTLISTENER_BASE_URL=https://www.courtlistener.com/api/rest/v4/
COURTLISTENER_TIMEOUT=30
COURTLISTENER_LOG_LEVEL=INFO
COURTLISTENER_DEBUG=false
HOST=0.0.0.0
MCP_PORT=8785
ENVIRONMENT=production

Running the Server

uv run python -m app.server

This will start the server at:

Host: 0.0.0.0 (accessible from external connections)
Port: 8785
Endpoint: http://localhost:8785/mcp/

Or use the VS Code task: Run MCP Server

💡 Usage Examples

See app/README.md for detailed tool usage and examples, including search, citation, statute, and regulations queries.

🧪 Testing

uv run pytest
uv run pytest --cov=app --cov-report=term-missing

See tests/README.md for test suite details, coverage, and troubleshooting.

🔧 Development

uv run ruff format .
uv run ruff check .
uv run mypy app/
uv run pip-audit

🚨 Troubleshooting

Common Issues

"unauthorized" or "throttled" errors:

Ensure your API key is set correctly in .env
Verify you're using Token authentication (not just the raw token)
Check your API usage in your CourtListener profile

Container won't start:

Check logs: docker logs court-listener-mcp
Verify .env file exists and is readable
Ensure port 8785 is not already in use

Connection refused:

Wait a few seconds for the server to start
Verify the container is running: docker ps
Check the correct port mapping

See app/README.md and tests/README.md for additional troubleshooting.

📚 Documentation

🐳 Docker Image Registries

Pre-built images are available from:

Registry	Image
Docker Hub	`vesha/court-listener-mcp:latest`
GitHub Container Registry	`ghcr.io/travis-prall/court-listener-mcp:latest`
Private Registry	`docker.vesha.net/court-listener-mcp:latest`

Images are published to the GitHub Container Registry automatically by GitHub Actions on every push to main and on v* version tags. Multi-arch builds (linux/amd64 and linux/arm64) are supported. Docker Hub and the private docker.vesha.net registry are published manually with the same multi-arch image (docker buildx build --platform linux/amd64,linux/arm64), and versioned tags follow the X.Y.Z + latest + git-short-SHA conventions.

⚖️ License

This project is licensed under the PolyForm Noncommercial License. You are free to use, modify, and self-host this MCP server for personal, academic, or non-commercial legal research.

Integration into a commercial product, hosted service, or paid application is strictly prohibited without explicit permission.

💖 Support

If you find this project useful, please consider supporting its maintainer. It's completely optional, but always appreciated:

Prefer crypto? See DONATE.md for donation addresses.

Ready to use! The CourtListener ++ MCP Server provides production-ready access to legal data, federal statutes, and federal rulemaking documents through 30 comprehensive MCP tools.