Skip to main content
Glama
DocketBird MCP Server

DocketBird MCP Server

DocketBird MCP Server

An MCP server for searching and downloading court documents via the DocketBird API. Deployed on DigitalOcean with Docker, using OAuth 2.0 so each user brings their own DocketBird API key.

Tools

Whole-corpus search tools work across DocketBird's full index (all courts, all cases); case-specific tools require the account to have followed the case; account tools act on your firm's own DocketBird data.

Tool

Description

docketbird_search_cases

Search ALL cases by name or case number (cursor-paginated)

docketbird_fulltext_search

Full-text search of filing bodies across the whole corpus; my_cases_only restricts to your firm's cases

docketbird_get_case

One case's metadata + complaint pointer (no docket fetch)

docketbird_get_case_details

Full docket sheet: case info + paginated document list

docketbird_search_documents

Match docket-entry titles/descriptions within one case

docketbird_get_document

One document's metadata and download links (no bytes)

docketbird_get_document_text

Extracted plain text of a filing (pageable via offset)

docketbird_download_document

Retrieve a single document's content (or save it locally in stdio)

docketbird_download_files

List a case's documents with direct download links (or save them locally in stdio)

docketbird_ask_litigation_graph

Natural-language questions about parties, attorneys, firms, judges (federal civil, ~30% coverage since July 2025)

docketbird_list_courts

Look up courts live from the API (search, court_system, court_type)

docketbird_list_court_systems

List every covered court system

docketbird_list_cases

List cases on your account (company or user scope)

docketbird_get_calendar

Calendar entries for a case, or company-wide (days window)

docketbird_create_autocalendar

Create an autocalendar for a case (queued; court fees may apply)

docketbird_follow_case

Follow a case so DocketBird monitors new filings

Using these tools from an agent: a ready-to-install Claude skill lives in skills/docketbird-mcp/, covering the case-ID format, each tool, and common research workflows.

Related MCP server: legal-mcp

Requirements

  • Python 3.11

  • uv package manager

Setup

  1. Install uv:

curl -LsSf https://astral.sh/uv/install.sh | sh
  1. Create and activate a virtual environment:

uv venv
source .venv/bin/activate
  1. Install dependencies:

uv pip install -r requirements.txt

Running the Server

# stdio transport (uses DOCKETBIRD_API_KEY env var, no OAuth)
DOCKETBIRD_API_KEY="your-key" python docketbird_mcp.py --transport stdio

# HTTP transport with OAuth (Streamable HTTP at /mcp)
python docketbird_mcp.py --transport http
# Then visit http://localhost:8080/signup to create an account

Note: All diagnostic logging goes to stderr, never stdout. This keeps the stdio JSON-RPC stream clean — writing logs to stdout would corrupt it and break the client.

Environment Variables

Variable

Mode

Default

Description

DOCKETBIRD_API_KEY

stdio

(none)

API key used for all requests in stdio mode (no OAuth). Required for stdio.

SERVER_URL

http

http://localhost:8080

Public base URL. Used as the OAuth issuer/resource URL and for redirects. Must match the URL clients connect to.

DATA_DIR

http

./data

Directory holding the SQLite auth database. Mounted as a volume in Docker.

See .env.example for a template.

Connecting to the Deployed Server

See docs/CONNECTING.md for the full walkthrough, or DocketBird_MCP_Installation_Guide.pdf for the same guide with screenshots.

Quick version

  1. Register at https://app.docketbird-mcp.com/signup with your email, password, and DocketBird API key

  2. In Claude.ai or Claude Desktop, add a remote MCP server with URL https://app.docketbird-mcp.com/mcp

  3. Claude auto-discovers OAuth, redirects you to log in, and connects

Stdio (local development)

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json) or Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "docketbird-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/docketbird-mcp-plus",
        "python",
        "docketbird_mcp.py"
      ],
      "env": {
        "DOCKETBIRD_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Authentication

The server uses OAuth 2.0 with PKCE for HTTP mode. Each user registers with their own DocketBird API key, which is stored server-side and attached to OAuth tokens. The SDK handles the protocol endpoints automatically:

  • /.well-known/oauth-authorization-server - OAuth metadata discovery

  • /register - Dynamic Client Registration

  • /authorize - Authorization endpoint (redirects to /login)

  • /token - Token exchange and refresh

In stdio mode, the DOCKETBIRD_API_KEY env var is used directly (no OAuth).

Security

  • OAuth 2.0 with PKCE (no shared API key on the server)

  • Per-user DocketBird API keys stored in SQLite with bcrypt-hashed passwords

  • Rate limiting: 30 requests per 60 seconds per IP

  • HTTPS-only downloads with SSRF domain allowlist

  • Path traversal protection on file downloads

  • Container runs as non-root mcpuser

  • GitHub Actions pinned to commit SHAs

  • Dependencies pinned to exact versions

  • Expired tokens, auth codes, and pending sessions are purged hourly (in both stdio and HTTP modes)

Downloads — where files go: over a remote (HTTP) connection the download tools return document content and links to your client; a save_path is ignored (it would write to the server, not your machine). In local stdio mode, pass a save_path to save to your own machine.

Development & Testing

Install the dev extras and run the test suite:

uv pip install -e ".[dev]"   # or: pip install -e ".[dev]"
pytest

The suite (tests/) runs fully offline — network calls are faked — and covers the security helpers (path/URL validation, filename sanitization), pagination math, the rate limiter, error formatting, the streaming download size cap, and the remote-vs-local download behavior (inline content / links vs save-to-disk).

For a deeper look at how the server is wired together (OAuth flow, request lifecycle, database schema, security model), see docs/ARCHITECTURE.md.

Contributing and Security

Contributions are welcome; see CONTRIBUTING.md for setup, testing, and pull-request guidance. Report suspected vulnerabilities privately as described in SECURITY.md.

Troubleshooting

  • stdio client shows JSON parse errors: ensure nothing in your environment writes to stdout. This server logs to stderr by design; custom forks should keep it that way.

  • No DocketBird API key available: in stdio mode set DOCKETBIRD_API_KEY; in HTTP mode complete the OAuth login at /signup → connect from Claude.

  • OAuth login loops or "Invalid redirect URI": confirm SERVER_URL exactly matches the public URL clients use (scheme + host, no trailing slash).

  • Changed your DocketBird API key but tools still fail: use /change-api-key. It validates the new key against DocketBird and clears stale access tokens so the new key takes effect immediately.

Deployment

Deployed via Docker and GitHub Actions. Pushes to main trigger automatic deployment.

  • Domain: app.docketbird-mcp.com

  • Docker volume: docketbird-data at /app/data (SQLite auth database)

  • Health check: https://app.docketbird-mcp.com/health — returns {"status":"ok","service":"docketbird-mcp","version":"<git-sha>"}, where version is the deployed commit (set by the deploy workflow via GIT_SHA), so a single curl confirms exactly which build is live.

  • Caddy reverse proxy handles HTTPS (Let's Encrypt)

Local Docker Build

docker build -t docketbird-mcp:latest .

docker run -d \
  --name docketbird-mcp \
  --restart=always \
  -e SERVER_URL="http://localhost:8040" \
  -v docketbird-data:/app/data \
  -p 8040:8080 \
  docketbird-mcp:latest

Reference Data

  • case_types.json - Case type abbreviations and examples (no API endpoint exists for these)

  • courts.json - Historical snapshot of court codes, frozen 2026-05-31. No longer read by any tool — docketbird_list_courts serves the live GET /courts endpoint.

Acknowledgment

This project is built upon the original docketbird-mcp developed in conjunction with @federicoburman and the Gravix.AI team.

Available Tools

16 tools
docketbird_ask_litigation_graphA
Read-onlyIdempotent

Ask a natural-language question of DocketBird's litigation graph: parties, attorneys, law firms, judges, courts, and their connections.

This is the ONLY source of party/attorney/firm/judge relationships — the
docket endpoints do not return them. Examples: "What attorneys appeared
for Google in the Northern District of California?", "Every case where
Firm A appeared opposite Firm B", "What judges has Quinn Emanuel appeared
before?".

COVERAGE CEILING — read before trusting absence: the graph covers federal
civil cases active in DocketBird's data flows since July 2025 (roughly 30%
of federal civil cases). No criminal, bankruptcy, or state-court matters.
Zero records means "not in the graph," NEVER "no such cases exist" — do
not present an empty result as a finding that something doesn't exist.

Behavior:
- Slow: responses can take 10-25 seconds (an AI model interprets the
  question, then queries the graph).
- Result shape varies with the question; entity IDs accompany names.
- At most 200 records per response; 'truncated' means more matches exist —
  narrow the question to see the rest.
- Attorney email addresses are never included. This tool reports exactly
  what the API returned — it never invents contact details.

Args:
    question: The natural-language question (max 1000 characters).

Inputs: question (required). Returns: result

docketbird_create_autocalendarA

Create an autocalendar for a case, so its deadlines and hearings appear in your company's calendar (docketbird_get_calendar).

Practice scope: acts on YOUR DocketBird account. Creation is queued — the
case's docket sheet is updated first, then the autocalendar is built.
Court (PACER) fees may apply for the docket update.

When to use:
- Adding a case's deadlines to the firm's calendar
- After following a case you need to track dates for

Args:
    case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697')

Inputs: case_id (required). Returns: result

docketbird_download_documentA

Download a specific document by ID.

Returns the document content to **you** (the client) as an embedded resource
so you can read or save it — this works over the remote HTTP connection. In
local stdio mode, passing ``save_path`` instead writes the file to that folder
on your own machine (the server runs locally there).

When to use:
- User wants to retrieve a specific filing
- After searching for documents
- Downloading individual documents

Args:
    document_id: DocketBird document ID
    save_path: Local folder to save into. Only honored in local stdio mode,
               where the server shares your filesystem. Ignored over a remote
               HTTP connection (the file would land on the server, not your
               machine), where the content is returned to you directly.

Returns:
    - Remote, or local with no save_path: a list of content blocks — a text
      summary plus an embedded resource holding the document bytes (base64),
      capped at MAX_INLINE_SIZE. If the document exceeds that cap, returns a
      text message with its direct download URL instead of inlining it.
    - Local stdio with save_path: a text confirmation of the saved file path.
    - On error / unavailable / restricted: a plain text message.

Inputs: document_id (required), save_path.

docketbird_download_filesA

List or save every available document for a case.

A case can hold many large PDFs, so over a remote HTTP connection this returns
a list of per-document **direct download links** (pre-signed, short-lived)
rather than inlining every file — fetch the ones you need, or call
``docketbird_download_document`` for a single document's content. In local
stdio mode, passing ``save_path`` instead streams every file to that folder on
your own machine.

When to use:
- User wants the complete case file archive
- Bulk document retrieval
- Surveying which filings are available to download

Args:
    case_id: DocketBird case ID
    save_path: Local folder to save into. Only honored in local stdio mode,
               where the server shares your filesystem. Over a remote HTTP
               connection it is ignored and download links are returned instead.

Returns:
    str: Markdown. Remote (or local with no save_path) lists each available
    document's title, ID, and direct download URL, plus counts of
    restricted/unavailable filings. Local stdio with save_path reports how
    many files were saved to disk and any that were skipped or failed.

Inputs: case_id (required), save_path. Returns: result

docketbird_follow_caseA

Follow a court case so DocketBird monitors it for new filings.

When to use:
- User wants to track/monitor a case for new documents
- Setting up ongoing monitoring of a docket

Followed federal cases are checked about twice weekly; state cases about
once weekly. New filings trigger DocketBird's new-documents notifications.

Args:
    case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697')

Inputs: case_id (required). Returns: result

docketbird_get_calendarA
Read-onlyIdempotent

Get calendar entries (deadlines, hearings, conferences) from your company's autocalendars — for one case, or company-wide.

Practice scope: this reads YOUR company's autocalendars (requires a full
DocketBird account with autocalendars created; see
docketbird_create_autocalendar).

Two scopes, one tool:
- With case_id: every calendar entry for that case.
- Without case_id: entries across ALL cases your company has active
  autocalendars for, within the next `days` days — "what deadlines does my
  firm have coming up?"

The company-wide scope is served from a pre-computed rollup; if it has
never been built, the API starts building it and this tool says to retry
in a minute or two.

Args:
    case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697').
             Omit for the company-wide scope.
    days: Company-wide scope only: how many days ahead to include,
          starting today (default 7, clamped to 1-90 upstream).
          Ignored when case_id is given.

Inputs: days, case_id. Returns: result

docketbird_get_caseA
Read-onlyIdempotent

Get one case's metadata, including a pointer to its complaint.

A lightweight, research-scope lookup: works for any case in DocketBird's
index (not just your account's cases) and does NOT fetch the docket, so it
can't hit the large-docket timeout. Use docketbird_get_case_details for the
full docket sheet, and docketbird_ask_litigation_graph for parties/attorneys.

When to use:
- Resolving a case ID (e.g. from docketbird_search_cases) to its metadata
- Jumping straight to the initiating complaint
- Checking PACER case ID / client code without pulling the docket

Args:
    case_id: DocketBird case ID (e.g., 'txwd-1:2022-cv-00398')

Inputs: case_id (required). Returns: result

docketbird_get_case_detailsA
Read-onlyIdempotent

Get a case's full docket sheet: case info plus its list of documents.

When to use:
- User wants the docket sheet (every filing in the case)
- Before downloading documents (to see what's available)

Notes:
- Parties and attorneys are NOT available from the docket endpoints; for
  them, use docketbird_ask_litigation_graph.
- The upstream /documents endpoint has no pagination: the entire docket is
  always fetched, and page/page_size only shape this response. Very large
  dockets can hit DocketBird's own ~29s gateway timeout (a 504).
- For a case's metadata alone (no docket fetch), use docketbird_get_case.

Args:
    case_id: DocketBird case ID (e.g., 'txnd-3:2007-cv-01697')
             Format: {court_id}-{district}:{year}-{type}-{number}
    page: Page number for documents (starts at 1, default 1)
    page_size: Number of documents per page (default 20, max 50)

Inputs: case_id (required), page, page_size. Returns: result

docketbird_get_documentA
Read-onlyIdempotent

Get one document's metadata and download links — without the bytes.

Lightweight lookup for a single filing: title, filing date, restricted
status, and (when retrieved) a direct PDF download link. Use
docketbird_download_document for the file content itself, or
docketbird_get_document_text for the extracted text.

When to use:
- Checking whether a filing is available/restricted before downloading
- Getting a direct PDF link to hand to the user
- Resolving a document ID from search results to its metadata

Args:
    document_id: DocketBird document ID (e.g., 'txwd-1:2022-cv-00398-00177')

Inputs: document_id (required). Returns: result

docketbird_get_document_textA
Read-onlyIdempotent

Get the extracted plain text of a court filing.

Returns what the document says (for summarizing, quoting, comparing) rather
than its metadata or PDF — those come from docketbird_get_document /
docketbird_download_document.

Availability varies: some documents aren't downloaded yet, some are scans
with no text layer, some docket entries are text-only stubs with no
document. When no text is available this returns a clear message — the PDF
may still be retrievable via docketbird_get_document.

When to use:
- Reading, summarizing, or quoting a filing's contents
- Pulling the complaint's text after docketbird_get_case points to it

Args:
    document_id: DocketBird document ID (e.g., 'txwd-1:2022-cv-00398-00177')
    offset: Character offset into the text to start from (for paging
            through long documents; default 0).
    max_chars: Maximum characters to return (default 50000, max 200000).

Inputs: document_id (required), offset, max_chars. Returns: result

docketbird_list_casesA
Read-onlyIdempotent

List the cases on YOUR DocketBird account (practice scope).

This is your firm's tracked caseload only. To search all cases across all
courts, use docketbird_search_cases.

When to use:
- User wants to see their own/their firm's tracked cases
- Finding case IDs for calendar, follow, or autocalendar operations

Args:
    scope: 'company' for all company cases, 'user' for personal cases
    page: Page number (starts at 1, default 1)
    page_size: Results per page (default 20, max 50)

Inputs: scope (required), page, page_size. Returns: result

docketbird_list_courtsA
Read-onlyIdempotent

Look up the courts DocketBird covers (live from the API).

Research scope — the full court set, independent of your account.

Behavior:
- No arguments: the curated set (~300 rows: all federal courts plus named
  state courts), followed by the case-type reference for the case ID format.
- search: free-text lookup by court name ('Southern District of New York'),
  abbreviation ('S.D.N.Y.'), or court_id ('nysd'); returns up to 25 ranked
  matches from the FULL set of enabled courts, including several thousand
  unlisted state courts. The fastest way to resolve a court to its court_id.
- court_system: browse every court inside one system (identifier from
  docketbird_list_court_systems), including unlisted ones.

Args:
    search: Free-text court lookup (name, abbreviation, or court_id).
    court_system: Court-system identifier to browse (e.g. 'uc-tx-distct').
    court_type: Optional filter: 'federal' or 'state'.

Inputs: search, court_type, court_system. Returns: result

docketbird_list_court_systemsA
Read-onlyIdempotent

List every court system DocketBird covers (live from the API).

Returns the federal system plus each state court system, with a
human-readable name and how many covered courts each holds. Use a
court_system_id with docketbird_list_courts(court_system=...) to browse the
courts inside a system, including unlisted courts that don't appear in the
default listing. Changes rarely; safe to cache.

When to use:
- Discovering what state-court coverage exists
- Getting the identifier to browse one system's courts

Inputs: no named parameters. Returns: result

docketbird_search_casesA
Read-onlyIdempotent

Search ALL cases in DocketBird's index by case name or case number.

Research scope: this covers every court and every case DocketBird knows
about — not just cases on your account (that's docketbird_list_cases).

Matching: case-number-shaped queries (e.g. '2:2017-bk-00112' or
'17-bk-112') match on filing year, case type, and terminating digits;
anything else matches against case names.

Date filters match in tiers: cases with an exact filing date match at day
precision; cases with only a known filing year match at year granularity;
cases with no known date are included unless exclude_unknown_dates=True.

When to use:
- Finding a case's DocketBird ID from a name or number
- Checking whether a company has been sued (pair with
  docketbird_ask_litigation_graph for who represented whom)

Args:
    query: Case name (e.g. 'Immedia Semiconductor') or case number
           (e.g. '4:2022-cv-04775'). Max 500 chars.
    court_id: Comma-separated court restriction; each entry may be a slug
              ('nysd'), an abbreviation ('S.D.N.Y.'), or a full court name.
    filed_after: Only cases filed on/after this date (YYYY-MM-DD, inclusive).
    filed_before: Only cases filed on/before this date (YYYY-MM-DD, inclusive).
    exclude_unknown_dates: Drop cases whose filing date and year are both
                           unknown from date-filtered results (default False).
    size: Results per page (default 25, max 50).
    cursor: Pagination cursor from a previous response's next-page note.

Inputs: query (required), size, cursor, court_id, +3 more. Returns: result

docketbird_search_documentsA
Read-onlyIdempotent

Find docket entries in ONE case whose title/description contains a term.

This matches docket-entry METADATA only (the title and description shown on
the docket sheet), not the text inside the filings. To search the full text
of filing bodies — across all courts or within one case — use
docketbird_fulltext_search instead.

When to use:
- User wants filings TITLED a certain way in a known case
  (e.g. docket entries labeled "motion to dismiss")
- Narrowing down a docket sheet before download

Note: the upstream /documents endpoint has no pagination, so the entire
docket is always fetched and matched in memory; very large dockets can hit
DocketBird's own ~29s gateway timeout (a 504).

Args:
    case_id: DocketBird case ID
    search_term: Term to match against docket-entry titles/descriptions
    page: Page number (starts at 1, default 1)
    page_size: Results per page (default 20, max 50)

Inputs: case_id (required), search_term (required), page, page_size. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose. Full-text search vs. docket entry search, single document download vs. bulk, metadata-only vs. full docket, and the unique litigation graph tool prevent any ambiguity.

    Naming Consistency5/5

    All tools follow a consistent 'docketbird_verb_noun' pattern in snake_case, with verbs like search, get, list, download, create, follow, ask. No mixing of conventions.

    Tool Count5/5

    16 tools cover the essential functionalities of searching, listing, downloading, calendar management, and litigation graph queries without being excessive or sparse.

    Completeness4/5

    Core workflows (search, retrieve, download, calendar, monitor) are covered. Minor gaps like missing unfollow_case or delete_autocalendar exist, but agents can still operate effectively.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables US case law search, citation parsing, practice management via Clio, and federal court filings through PACER.
      -
    • F
      license
      A
      quality
      D
      maintenance
      Wraps the CourtListener API for real-time federal docket monitoring, with pluggable client-list connectors (SharePoint, Excel, webhook) and tools for docket monitoring and client matching via elicitation.
      12
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables users to search and retrieve court docket records across US state, county, and federal courts, including PACER party searches, and to get full case details.
      91 npm
      MIT