CourtListener MCP Server

Production-ready Model Context Protocol (MCP) server for CourtListener legal data. It exposes legal research tools over MCP (stdio and Cloudflare Worker Streamable HTTP), with deployment-ready hosted OAuth, structured logging, caching, and CI testing.

What This Repository Provides

• MCP v2 server built on @modelcontextprotocol/server
• 52 governed tools, including three asynchronous job-control tools backed by CourtListener API v4
• Two deployment contracts: local stdio and hosted Cloudflare Worker remote OAuth
• Hosted MCP OAuth transport via Cloudflare Workers OAuth Provider
• Worker-owned browser auth handoff for hosted sign-in and approval
• Optional queue-backed async MCP jobs for durable hosted execution
• Optional Cloudflare Analytics Engine telemetry for route, DO, Turnstile, and async job signals
• Optional Turnstile enforcement on session bootstrap and AI chat routes
• Built-in health checks and metrics endpoints for operations
• Prebuilt MCP client config examples in configs/

Repository Structure

• src/ core server, tool handlers, API integration, worker runtime
• src/web-spa/ browser portal (React SPA, Tailwind CSS v4); see src/web-spa/DESIGN.md
• configs/ ready-to-use MCP client configs for local, self-hosted, and hosted clients
• docs/ deployment, testing, and operational documentation
• test/ unit/integration/e2e test suites
• scripts/ deployment helpers, diagnostics, key management

Quick Start

1. Use the hosted remote endpoint (fastest)

Best for ChatGPT, Claude, Codex, and other remote clients that should not run the server locally:

{
  "mcpServers": {
    "courtlistener": {
      "url": "https://courtlistener-mcp..workers.dev/mcp",
      "transport": "streamable-http"
    }
  }
}

2. Run locally from a checkout

Best for privacy, local development, and bring-your-own-auth setups. The npm package is not currently published, so the local stdio server should be run from this repository checkout:

• Download ZIP: https://github.com/blakeox/courtlistener-mcp/archive/refs/heads/main.zip
• Download tar.gz: https://github.com/blakeox/courtlistener-mcp/archive/refs/heads/main.tar.gz

git clone https://github.com/blakeox/courtlistener-mcp.git
cd courtlistener-mcp
pnpm install
pnpm build
node dist/index.js --setup

Or run it directly:

node dist/index.js

If you want a local shell command after building:

npm link
courtlistener-mcp --setup

3. Develop or self-host the Cloudflare Workers topology

git clone https://github.com/blakeox/courtlistener-mcp.git
cd courtlistener-mcp
pnpm install
pnpm build
pnpm run dev:workers

dev:workers starts the local Edge and MCP Workers with their service binding. For a deployed self-hosted topology, authenticate Wrangler and use the