DocketBird MCP Server
DocketBird MCP Server lets you search, retrieve, and monitor U.S. court cases and filings via the DocketBird API.
Search whole corpus: Find any case by name/number (
docketbird_search_cases) or run full-text searches across filing bodies in all courts (docketbird_fulltext_search), optionally restricted to your firm's cases.Inspect cases: Get a case's metadata/complaint pointer (
docketbird_get_case) or its full docket sheet with paginated documents (docketbird_get_case_details).Find and read documents: Match docket-entry titles within a case (
docketbird_search_documents), fetch a document's metadata/links (docketbird_get_document), pull extracted plain text (docketbird_get_document_text), or download content (docketbird_download_document,docketbird_download_files).Explore the litigation graph: Ask natural-language questions about parties, attorneys, firms, and judges (
docketbird_ask_litigation_graph; federal civil only, ~30% coverage since July 2025).Look up courts: Browse all courts and court systems live from the API (
docketbird_list_courts,docketbird_list_court_systems).Manage your account's cases: List your firm's/user's cases (
docketbird_list_cases), follow cases for monitoring (docketbird_follow_case), view deadlines/hearings (docketbird_get_calendar), and create autocalendars (docketbird_create_autocalendar).
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@DocketBird MCP Server search for 'summary judgment' in case 3:23-cv-01234"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Search ALL cases by name or case number (cursor-paginated) |
| Full-text search of filing bodies across the whole corpus; |
| One case's metadata + complaint pointer (no docket fetch) |
| Full docket sheet: case info + paginated document list |
| Match docket-entry titles/descriptions within one case |
| One document's metadata and download links (no bytes) |
| Extracted plain text of a filing (pageable via |
| Retrieve a single document's content (or save it locally in stdio) |
| List a case's documents with direct download links (or save them locally in stdio) |
| Natural-language questions about parties, attorneys, firms, judges (federal civil, ~30% coverage since July 2025) |
| Look up courts live from the API ( |
| List every covered court system |
| List cases on your account (company or user scope) |
| Calendar entries for a case, or company-wide ( |
| Create an autocalendar for a case (queued; court fees may apply) |
| 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
Install uv:
curl -LsSf https://astral.sh/uv/install.sh | shCreate and activate a virtual environment:
uv venv
source .venv/bin/activateInstall dependencies:
uv pip install -r requirements.txtRunning 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 accountNote: 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 |
| stdio | (none) | API key used for all requests in stdio mode (no OAuth). Required for stdio. |
| http |
| Public base URL. Used as the OAuth issuer/resource URL and for redirects. Must match the URL clients connect to. |
| http |
| 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
Register at https://app.docketbird-mcp.com/signup with your email, password, and DocketBird API key
In Claude.ai or Claude Desktop, add a remote MCP server with URL
https://app.docketbird-mcp.com/mcpClaude 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
mcpuserGitHub 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_pathis ignored (it would write to the server, not your machine). In local stdio mode, pass asave_pathto 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]"
pytestThe 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 setDOCKETBIRD_API_KEY; in HTTP mode complete the OAuth login at/signup→ connect from Claude.OAuth login loops or "Invalid redirect URI": confirm
SERVER_URLexactly 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.comDocker volume:
docketbird-dataat/app/data(SQLite auth database)Health check:
https://app.docketbird-mcp.com/health— returns{"status":"ok","service":"docketbird-mcp","version":"<git-sha>"}, whereversionis the deployed commit (set by the deploy workflow viaGIT_SHA), so a singlecurlconfirms 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:latestReference 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_courtsserves the liveGET /courtsendpoint.
Acknowledgment
This project is built upon the original docketbird-mcp developed in conjunction with @federicoburman and the Gravix.AI team.
Available Tools
16 toolsdocketbird_ask_litigation_graphARead-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_fulltext_searchARead-onlyIdempotent
Full-text search of the BODIES of court filings across DocketBird's entire document index — all courts, all cases, not just your account.
This searches what the filings actually say, not what they are titled. To
match docket-entry titles within one case, use docketbird_search_documents.
When to use:
- Scanning recent filings for a company, industry, or legal topic
(e.g. new suits naming a target company — set sort='recency')
- Finding every filing whose text mentions a term, phrase, or citation
- Practice research inside your firm's own cases (set my_cases_only=True)
Scope boundary: with my_cases_only=False (default) this is cross-corpus
RESEARCH over public court records. With my_cases_only=True it is limited
to cases associated with your firm's account (resolved from your API key).
Query syntax:
- space / and: all terms must appear. or: either term.
- -term: exclude (the word 'not' is NOT supported).
- term* or term!: word endings (end of word only).
- /n, /s, /p: terms within n words / same sentence / same paragraph.
- "...": exact phrase. Email addresses and legal symbols (§, ¶) work.
Pagination contract (upstream cursors, bounded requests):
- next_cursor is the ONLY end-of-results signal. A page may hold fewer
than `size` documents — even zero — while more remain, because
restricted documents are removed after matching. Keep following the
cursor until it is null. The 'found' count may include documents that
will never be returned. Result window is the first 10,000 matches —
narrow with court_id/case_id/dates if you need the deep tail.
Args:
query: Full-text query (max 500 chars), e.g. '"summary judgment" and forfeit* -insurance'
court_id: Comma-separated court restriction; each entry may be a slug
('nysd'), an abbreviation ('S.D.N.Y.'), or a full court name.
case_id: Restrict to a single case by DocketBird case ID.
filed_after: Only documents filed on/after this date (YYYY-MM-DD).
filed_before: Only documents filed on/before this date (YYYY-MM-DD).
my_cases_only: True = only your firm's cases (practice scope);
False = the whole corpus (research/marketing scope).
sort: 'relevance' (default) or 'recency' (most recently filed first).
size: Results per page (default 25, max 50).
cursor: Pagination cursor from a previous response's next-page note.
Inputs: query (required), size, sort, cursor, +5 more. Returns: result
docketbird_get_calendarARead-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_caseARead-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_detailsARead-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_documentARead-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_textARead-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_casesARead-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_courtsARead-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_systemsARead-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_casesARead-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_documentsARead-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
Scored across 16 tools
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.
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.
16 tools cover the essential functionalities of searching, listing, downloading, calendar management, and litigation graph queries without being excessive or sparse.
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
Search U.S. case law, fetch opinions, and ask matter-aware legal questions over your documents.
Search US federal and state court records through CourtListener and the RECAP archive
Read contacts, matters, invoices and documents; create contacts, matters and notes in Docketwise.
Search, read and cite documents. Add, replace and delete files with write access. OAuth required.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables legal research across 3,352 U.S. courts using the CourtListener API, providing access to case search, precedent analysis, judge patterns, citation validation, and federal PACER dockets through natural language queries.19 npm3MIT
- FlicenseNot gradedqualityDmaintenanceEnables US case law search, citation parsing, practice management via Clio, and federal court filings through PACER.-
- FlicenseAqualityDmaintenanceWraps 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-
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmMIT