Courtlistener MCP Server

CourtListener MCP Server

A Model Context Protocol server that gives AI assistants access to the CourtListener legal database (US federal + state court opinions, dockets, RECAP filings, PACER data, oral arguments, judges) and the Electronic Code of Federal Regulations via the official CourtListener API v4.

Use it with Claude Desktop, Claude Code, Cursor, VS Code, Windsurf, ChatGPT Desktop, or any MCP-compatible client.

Forked from Travis-Prall/court-listener-mcp. This fork adds a hosted endpoint, bring-your-own-key (BYOK) auth, a /health route, and Dockerfile hardening for production hosting. Tools and search semantics are unchanged.

Use the hosted endpoint (no install)

The Vaquill team runs a public instance for the community:

https://courtlistener-mcp.vaquill.ai/mcp/

You bring your own free CourtListener token from courtlistener.com/help/api/rest/, the server forwards it. We never see or store your key.

Claude Desktop / Claude Code

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "courtlistener": {
      "url": "https://courtlistener-mcp.vaquill.ai/mcp/",
      "headers": {
        "X-CourtListener-Token": "YOUR_COURTLISTENER_TOKEN"
      }
    }
  }
}

Cursor

.cursor/mcp.json:

{
  "mcpServers": {
    "courtlistener": {
      "url": "https://courtlistener-mcp.vaquill.ai/mcp/",
      "headers": { "X-CourtListener-Token": "YOUR_COURTLISTENER_TOKEN" }
    }
  }
}

VS Code (GitHub Copilot Chat)

.vscode/mcp.json:

{
  "servers": {
    "courtlistener": {
      "type": "http",
      "url": "https://courtlistener-mcp.vaquill.ai/mcp/",
      "headers": { "X-CourtListener-Token": "YOUR_COURTLISTENER_TOKEN" }
    }
  }
}

Claude Web (custom connector)

Settings → Connectors → Add custom connector → paste the URL and add X-CourtListener-Token as a header. Workspace owners only.

Windsurf, Continue, etc.

Any client that supports MCP streamable HTTP with custom headers works. For stdio-only clients, run the server locally (see below) or proxy with mcp-remote.

Tools

See app/README.md for parameter details.

Authentication

Two modes, in priority order:

1. Per-request header (BYOK) — preferred for hosted / shared deployments. Send the user's CourtListener key on every MCP request:
   • X-CourtListener-Token: <key> (preferred), or
   • Authorization: Token <key> (CourtListener's native scheme — only works if the MCP server itself isn't already gated by Authorization).
2. Server env fallback — set COURT_LISTENER_API_KEY on the server. Used when no per-request header is supplied. Leave unset on public instances to force BYOK and avoid burning the operator's quota.

If neither is provided, tools return a ValueError with a clear message.

Self-host

Docker

git clone https://github.com/Vaquill-AI/courtlistener-mcp.git
cd courtlistener-mcp
cp .env.example .env  # optionally set COURT_LISTENER_API_KEY for single-tenant
docker compose up -d
# server at http://localhost:8000/mcp/

Python (uv)

uv sync
uv run python -m app --transport http

Stdio (local CLI integration)

uv run python -m app --transport stdio

Add to Claude Desktop:

{
  "mcpServers": {
    "courtlistener-local": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/courtlistener-mcp", "python", "-m", "app", "--transport", "stdio"],
      "env": { "COURT_LISTENER_API_KEY": "your_token" }
    }
  }
}

Configuration

* Required only if running in single-tenant mode without BYOK.

Health check

curl https://courtlistener-mcp.vaquill.ai/health
# {"status":"healthy","service":"courtlistener-mcp","version":"..."}

Development

uv sync --dev
uv run pytest
uv run ruff format . && uv run ruff check .
uv run mypy app/

Credits & License

• Original implementation: Travis-Prall/court-listener-mcp
• Hosted by: Vaquill — courtlistener-mcp.vaquill.ai
• License: MIT (see LICENSE)

CourtListener data is provided by the Free Law Project under their respective terms.