CourtListener MCP Server

Production-ready Model Context Protocol (MCP) server for CourtListener legal data. It exposes legal research tools over MCP (stdio and HTTP), with deployment-ready support for local use, self-hosted remote deployments, hosted Cloudflare Workers OAuth, structured logging, caching, and CI testing.

What This Repository Provides

• MCP server built on @modelcontextprotocol/sdk
• 49 legal research tools backed by CourtListener API v4
• Three deployment contracts: local stdio, self-hosted remote HTTP, and hosted 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, inspector tooling, 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.<subdomain>.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. Self-host the HTTP runtime from source

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

4. Self-host with Docker

cp .env.production .env
docker compose -f docker-compose.prod.yml up -d

Publishing to npm

This repository is configured to publish from .github/workflows/release.yml when you push a version tag such as v1.0.5.

You have two supported auth paths:

1. Repository secret: create an npm publish token and store it as the GitHub Actions secret NPM_TOKEN.
2. Trusted publishing: connect the npm package to this GitHub repository and let npm trust GitHub Actions OIDC, with no token stored in GitHub.

Once one of those is configured, publish with:

git tag v1.0.5
git push origin v1.0.5

Deployment Modes

1. Local mode (stdio)

• Run the MCP server on the same machine as the client
• No hosted auth required
• Best for privacy-sensitive workflows, local development, and bring-your-own-hosting

2. Self-hosted remote mode

• Deploy the HTTP/streamable HTTP runtime on your own infrastructure
• Bring your own auth if you need it (OIDC_*, service token, proxy auth, etc.)
• Best for teams that want remote access without using the hosted CourtListener endpoint

3. Hosted remote mode

• Use the CourtListener Cloudfl

... View full README on GitHub