courtlistener-sdk

@us-legal-tools/courtlistener-sdk

TypeScript SDK and MCP server for CourtListener - the largest free legal database

Features • Installation • Authentication • Quick Start • API • MCP Server • CourtListener API Docs

Features

• ⚖️ Case Law - Access millions of legal opinions from federal and state courts
• 👨‍⚖️ Judge Data - Comprehensive judge profiles and biographical information
• 🎙️ Oral Arguments - Audio recordings with metadata
• 📚 Citation Tools - Advanced citation lookup and normalization
• 💼 PACER Integration - Federal court docket access
• 🔔 Real-time Alerts - Track changes to cases and dockets
• 🤖 MCP Server - AI-ready server for integration with Claude and other AI assistants
• 🔍 Advanced Search - Powerful search with Elasticsearch backend
• ✨ Type-safe - Full TypeScript support with auto-completion

Installation

# npm
npm install @us-legal-tools/courtlistener-sdk

# yarn
yarn add @us-legal-tools/courtlistener-sdk

# pnpm
pnpm add @us-legal-tools/courtlistener-sdk

# bun
bun add @us-legal-tools/courtlistener-sdk

Authentication

The CourtListener API requires authentication for most endpoints. Get your API token from CourtListener.

// Set via environment variable
process.env.COURTLISTENER_API_TOKEN = 'your-token';

// Or configure the axios instance directly
import { axiosInstance } from '@us-legal-tools/courtlistener-sdk';
axiosInstance.defaults.headers.common['Authorization'] = 'Token your-token';

Quick Start

Basic Search

import { getSearch } from '@us-legal-tools/courtlistener-sdk';

// Search for Supreme Court cases
const results = await getSearch({
  type: 'o', // 'o' for opinions
  q: 'miranda rights',
  court: 'scotus',
  order_by: 'score desc'
});

console.log(`Found ${results.count} cases`);
results.results.forEach(result => {
  console.log(`- ${result.caseName} (${result.dateFiled})`);
});

Get Case Details

import { getOpinionsId } from '@us-legal-tools/courtlistener-sdk';

// Get a specific opinion
const opinion = await getOpinionsId({ id: 123456 });

console.log(`Case: ${opinion.case_name}`);
console.log(`Court: ${opinion.court}`);
console.log(`Date: ${opinion.date_filed}`);
console.log(`Text: ${opinion.plain_text || opinion.html}`);

Search Judges

import { getSearch } from '@us-legal-tools/courtlistener-sdk';

// Search for judges
const judges = await getSearch({
  type: 'p', // 'p' for people/judges
  q: 'Ruth Bader Ginsburg',
  order_by: 'name_reverse asc'
});

judges.results.forEach(judge => {
  console.log(`${judge.name_full} - ${judge.court}`);
});

Get Audio Recordings

import { getAudio } from '@us-legal-tools/courtlistener-sdk';

// Get oral arguments
const audio = await getAudio({
  docket__court: 'scotus',
  argued_after: '2023-01-01'
});

audio.results.forEach(recording => {
  console.log(`${recording.case_name} - ${recording.date_argued}`);
  console.log(`Audio: ${recording.download_url}`);
});

API Reference

Search Endpoints

• getSearch - Universal search endpoint for all content types
• getSearchV4OpinionsClusters - Search opinion clusters
• getSearchV4People - Search judges and people
• getSearchV4OralArguments - Search oral arguments

Opinion Endpoints

• getOpinions - List opinions
• getOpinionsId - Get specific opinion
• getClusters - List opinion clusters
• getClustersId - Get specific cluster

Judge/Person Endpoints

• getPeople - List judges and people
• getPeopleId - Get specific person details
• getPersonDisclosures - Get financial disclosures

Docket Endpoints

• getDockets - List dockets
• getDocketsId - Get specific docket
• getDocketEntries - List docket entries
• getDocketAlerts - Manage docket alerts

Audio Endpoints

• getAudio - List audio recordings
• getAudioId - Get specific audio recording

Citation Endpoints

• getCitations - Citation lookup
• getCitationNormalize - Normalize citations

MCP Server

The MCP server allows AI assistants to interact with the CourtListener API.

Running the Server

# Using the SDK directly (requires COURTLISTENER_API_TOKEN env var)
COURTLISTENER_API_TOKEN=your-token npx @us-legal-tools/courtlistener-sdk/mcp

# Or if installed locally
cd node_modules/@us-legal-tools/courtlistener-sdk
COURTLISTENER_API_TOKEN=your-token npm run mcp:server

Integration with Claude

Add to your Claude configuration:

{
  "mcpServers": {
    "courtlistener": {
      "command": "npx",
      "args": ["@us-legal-tools/courtlistener-sdk/mcp"],
      "env": {
        "COURTLISTENER_API_TOKEN": "your-token"
      }
    }
  }
}

Search Types

Use the following types with the search endpoint:

• o - Opinions
• r - RECAP Archive
• d - Dockets
• p - People/Judges
• oa - Oral Arguments
• opinion-cluster - Opinion Clusters

Advanced Search

import { getSearch } from '@us-legal-tools/courtlistener-sdk';

// Complex search with filters
const results = await getSearch({
  type: 'o',
  q: 'first amendment',
  court: 'ca9 ca10 cafc',  // Multiple courts
  filed_after: '2020-01-01',
  filed_before: '2023-12-31',
  cited_gt: 50,  // Cited more than 50 times
  order_by: 'dateFiled desc',
  highlight: true
});

Error Handling

import { getOpinionsId } from '@us-legal-tools/courtlistener-sdk';

try {
  const opinion = await getOpinionsId({ id: 123456 });
} catch (error) {
  if (error.response?.status === 401) {
    console.error('Invalid API token');
  } else if (error.response?.status === 404) {
    console.error('Opinion not found');
  } else if (error.response?.status === 429) {
    console.error('Rate limit exceeded');
  } else {
    console.error('API error:', error.message);
  }
}

Rate Limiting

CourtListener has rate limits based on your account type. Free accounts are limited to 5,000 requests per day.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Links

• npm Package
• GitHub Repository
• CourtListener Website
• CourtListener API Documentation
• Report Issues
• Request Features

Support

Need help? Check out our documentation or create an issue.

(back to top)