courtlistener-mcp-server

---

概览

CourtListener 超过 900 万篇判决意见的语料库及其 PACER 的 RECAP 镜像，收录了美国判例法和联邦法院记录。搜索判决意见和案卷、追踪引证网络、解析引证、查询法官和法院，并阅读口头辩论笔录及司法财务披露信息。

工具

工具	描述
courtlistener_search_opinions	在 900 多万份法院意见中进行全文搜索，支持字段语法以及法院、日期和状态筛选
courtlistener_get_opinion	获取意见集群的元数据和不同版本的文本（多数意见、协同意见、异议意见），并提供来源完整状态
courtlistener_get_citations	跟踪意见集群的引证网络：其引用的意见（citing）或引用它的意见（cited_by）
courtlistener_lookup_citation	将文本中的每条引证（例如“410 U.S. 113”）解析为集群 ID 和案件元数据
courtlistener_search_dockets	按案件名称、当事人、律师、法院和提交日期搜索 RECAP 联邦案卷
courtlistener_get_docket	获取联邦案卷的元数据和分页条目列表，并显示文档是否可用
courtlistener_get_parties	获取 RECAP 案卷中记录的当事人和律师
courtlistener_search_judges	按姓名、任命总统、法院和政治派别搜索法官
courtlistener_get_judge	获取法官的职位、教育背景、政治派别和 ABA 评级
courtlistener_lookup_courts	按管辖权类型、启用/停用状态和抓取器覆盖范围列出法院
courtlistener_search_oral_arguments	按案件名称、庭审记录文本、法院和辩论日期搜索上诉法院的口头辩论录音
courtlistener_get_oral_argument	获取一场口头辩论的合议庭成员、时长、MP3 链接和语音转文本记录
courtlistener_search_financial_disclosures	按法官和年份搜索司法财务披露文件
courtlistener_get_financial_disclosure	获取一份披露文件的逐项内容，并将编码值解码为美元金额范围

资源

资源	描述
courtlistener://reference/courts	管辖权代码、常见法院 ID、搜索类型代码、速率限制和维护时段

对于不显示资源的客户端，管辖权代码也列在 courtlistener_lookup_courts 的 jurisdiction 参数中。

提示词

提示词	描述
courtlistener_research_topic	为某个主题或问题生成结构化的法律研究计划

能力参考

结果页大小接受正整数，并会限制发出的请求：搜索/引证为 20 条，当事人为 10 条，案卷条目为 50 条。两种响应形式都包含 page_sizing（requested、bounded、actual、upstream）。上游搜索/披露页面至少包含 20 行；当事人/条目使用固定的 20 行分页；引用某意见的结果会先对被引用 ID 列表进行切片，再进行搜索。返回的页面会保留；空页/末页以及页面级筛选可能导致返回的行数更少。请使用原生游标继续翻页，而不要增大请求的结果数量。

courtlistener_search_opinions _工具

• q 为必填项，接受 CourtListener 字段语法（caseName:"roe v wade"、court_id:scotus、judge:"Alito"）以及 AND / OR / NOT；可按 court、filed_after / filed_before 和 status 筛选，并通过 order_by 排序（默认值为 score desc，也可选 dateFiled desc、dateFiled asc、citeCount desc）；每页 20 条结果，通过 next_cursor 继续翻页
• 每条结果都包含 cluster_id（供 courtlistener_get_opinion 和 courtlistener_get_citations 使用）、docket_id、cite_count、snippet，以及包含意见 ID、type、author_id 和 local_path 的不同版本 opinions[]；totalCount 和 effectiveQuery 用于报告匹配结果
• 省略 status 时，默认采用 CourtListener 的 Published 状态；也可选择一种出版状态，包括 In-chambers 和 Relating-to。

---

courtlistener_get_opinion _工具

• 必须提供 cluster_id；收到大纲响应后，sections: ["opinion_<id>", ...] 可提取特定变体；如果集群中没有指定名称，则会报错 unknown_section
• 集群元数据（案件名称、court_id、引文、cite_count、先例状态、摘要、诉讼立场、docket_id），以及每个变体的 html_text、plain_text、cites[]、download_url 和 type_label；此标签与 courtlistener_search_opinions 报告的相同
• 小型响应使用 kind: "full"。超大的变体或元数据会返回有界的 outline，随后通过 retrieval.next_cursor 返回带类型的 page 响应；重复使用原始 ID 和选择，并将 cursor 设为下一个游标，直到其为 null。
• 保留所提供的 plain_text；仅含标记的变体会转换为易读文本，其中包含段落、表格、列表、脚注和解码后的实体。html_text 保留原始来源，并以围栏文本形式呈现。搜索和引文片段使用相同的易读规范化方式。
• variants_completion 报告有界来源遍历是否已完成，以及上游剩余的变体游标。docket_enrichment 会区分 not_linked、resolved、source_fields_absent 和 lookup_failed，并提供经过清理的失败类别；取消操作会向上传播。

---

courtlistener_get_citations _工具

• 必须提供 cluster_id；direction 可设为 cited_by（默认值，引用此意见的意见）或 citing（此意见引用的意见）；可选过滤条件包括 court 和 filed_after；每页最多返回 20 条结果，使用 cursor 获取后续页面
• 每行包含 cluster_id、court_id、date_filed、cite_count 和 snippet；对于 citing，总数统计未过滤的被引用意见列表；即使筛选后的页面为空，next_cursor 仍可能有值。source_variants_completion 和 total_is_partial 用于说明 observed_total；变体不完整时，该值为下限，并且会省略精确的 totalCount 尾注。
• 对于 citing，cursor 是非负安全十进制整数偏移量（01、+1、1.0 和 1. 均表示 1）；格式错误的偏移量会在发出任何请求前报错 invalid_cursor。偏移量达到或超过末尾时，将返回空页面，并附上来源名称和未过滤的不同意见总数，且不会执行搜索。cited_by 游标保持不透明。

---

courtlistener_lookup_citation _工具

• citation 接受一条引文或最长 64,000 个字符的文本段落，并解析其中的每条引文；max_court_lookups（默认值为 4，最大值为 20，设为 0 可跳过）限制为查询法院名称而发出的案卷请求数
• 每条引文对应一个 matches[] 条目，包含 status（200 表示一个案件，300 表示多个候选项，400 表示无法识别的法律报告，404 表示无匹配项，429 表示超出每次请求的引文上限）和 status_label；每个 clusters[] 条目包含 cluster_id、docket_id、court_id 和 court_resolution（resolved、no_docket、lookup_failed、over_budget；只有最后一种情况值得通过提高预算重试）
• 无法解析的引文会作为条目返回，而不会报错；只有完全没有可解析引文的文本才会报错 not_found。CourtListener 按提交的每条引文计量此端点，且不受每次请求限制的影响

---

courtlistener_search_dockets _工具

• 必须提供 q，它会匹配案件名称、案卷编号、当事人和律师姓名；party_name（与 q 取 AND 条件）、court 和 filed_after / filed_before 可缩小结果范围；每页 20 条结果，使用 next_cursor 获取后续页面
• 每个案卷包含 docket_id、parties、attorneys、firms、suit_nature、assigned_to / referred_to，以及最多 3 份带有 is_available 和 RECAP filepath_local URL 的 sample_documents；每个响应都会附带一条 coverage_note，说明 RECAP 对 PACER 的覆盖并不完整

courtlistener_get_docket _工具

• 必须提供 docket_id；每页包含 20 条记录（CourtListener 会忽略 entries_page_size），使用 entries_page 遍历
• 返回案卷元数据、total_entries、next_cursor（下一页的 entries_page 编号），以及 entries[]；其中的 documents[] 包含 is_available、page_count 和 filepath_local；is_available: false 的文档需要通过 PACER 获取，且此工具不提供获取方式
• CourtListener 未提供数字总数时，total_entries 为 null，包括最后一页；呈现的总数显示为 unknown。不会以返回的记录数代替总数。

---

courtlistener_get_parties _工具

• 必须提供 docket_id；cursor 接受不透明的 next_cursor 令牌，而非页码；传出的 page_size 上限为 10，CourtListener 也可能不遵循该值
• 每个当事方包含 name、其在该案卷中的 role，以及包含 name、contact_raw、role_code / role（代码 5–9 表示已不再担任该案卷的律师）和 date_action 的 attorneys[]；如果上游提供总数，total_parties 使用该值；否则，单页结果会计数，或保持为 null
• attorney_resolution 会报告已解析、已耗尽或已达上限的查询、未解析的 ID，以及剩余的上游名册游标。解析最多进行五个名册页面；如果本地请求预算阻止获取后续页面，也会停止。已获取的记录会予以保留。对于每位律师，resolution 会区分字段为空的已解析记录、耗尽后出现的 not_found，以及达到上限后出现的 not_fetched。上游名册／变体游标描述完整性；这些工具不接受它们作为新的检索输入。

---

courtlistener_search_judges _工具

• 必须提供 q；可按 appointer（总统姓氏）、court 和 political_affiliation（d、r、i、l、g、u）筛选；每页 20 条结果，使用 next_cursor 继续
• 结果包含 person_id（用于 courtlistener_get_judge）、作为标签而非代码的 political_affiliation 和 aba_rating，以及 current_position：优先选择没有终止日期的职位；如果有多个或没有符合条件的职位，则选择开始日期最晚的职位

---

courtlistener_get_judge _工具

• 必须提供 person_id；职位数据最多获取至页面数上限；如果长记录超出上限，truncated 和 positionsShown 会报告这一情况
• 职位（司法职位，以及通过 job_title 和 organization_name 描述的非司法职务）、教育经历、政治归属、ABA 评级和 fjc_id；编码字段会同时保留原始代码和标签（position_type_label、termination_reason_label、degree_label）
• 日期会保留 CourtListener 记录的精度，见 dob_granularity、dod_granularity、date_start_granularity 和 date_termination_granularity（year、month 或 day）

---

courtlistener_lookup_courts _工具

• 可按 jurisdiction（22 个 CourtListener 代码之一，例如 F、FD、FB、S、SA；完整表格见 courtlistener://reference/courts）、status（默认为 active，也可为 inactive 或 any）和 has_opinion_scraper 筛选；实时记录每页 20 条，使用 page 遍历
• courts[] 包含 id（其他所有工具都根据该法院 ID 进行筛选）、citation_string、jurisdiction 和抓取器标志；all_matching_court_ids 会以零请求成本列出捆绑快照中的所有匹配项；匹配项超过 1,000 个时，该字段为空，因此请检查 all_matching_court_ids_complete

---

courtlistener_search_oral_arguments _工具

• 必须提供 q，用于匹配案件名称和庭审记录文本；可按 court 和 argued_after / argued_before 筛选；每页 20 条结果，使用 next_cursor 继续
• 结果包含 audio_id（用于 courtlistener_get_oral_argument）、panel_ids（用于 courtlistener_get_judge）、duration_seconds、snippet，以及两个 MP3 链接：原审法院提供的 download_url，以及 CourtListener 的持久副本 local_path

---

courtlistener_get_oral_argument _工具

• 必须提供 id（来自搜索结果的 audio_id）；sections: ["transcript"] 用于选择转录文本。所选响应遵守相同的字节限制。
• 返回 panel_ids、duration_seconds、download_url、docket_id、has_transcript 和 transcript；超出限制的文本或元数据会使用 outline 和由游标驱动的 page 响应。此记录中没有庭审辩论日期；请从搜索结果或案卷中获取。

---

courtlistener_search_financial_disclosures _工具

• 可按 judge_id（person_id）和 year 筛选；每页 20 份申报文件，并使用 cursor 继续翻页。由于 CourtListener 不支持服务端年份筛选，year 仅筛选已获取的页面，因此如果某页为空但设置了 next_cursor，请继续翻页。
• 每份申报文件包含 disclosure_id、report_type、has_been_extracted、is_amended、pdf_url、按类别统计的 counts（投资、赠与、债务、职位、报销、协议、非投资收入和配偶收入），以及逐项列出的 gifts

---

courtlistener_get_financial_disclosure _工具

• 必须提供 disclosure_id；categories 用于选择 investments、debts、positions、reimbursements、non_investment_incomes、spouse_incomes、agreements 和 gifts（省略则返回全部）
• 返回申报文件元数据、counts 和请求的逐条记录，并将编码值和收入列解码为美元金额范围（N → $250,001 - $500,000）；超出限制的选项会使用 outline 和由游标驱动的 page 响应，包括单条记录超出预算的情况。

意见书、音频和申报文件检索会将每个序列化响应面（structuredContent 和完整的 content[]）限制在 24,000 UTF-8 字节以内。使用 cursor: retrieval.next_cursor 重复原始 ID，并保持 sections/categories 选择不变。目录页会自动引导至数据页。retrieval.ranges 使用 JSON Pointer 路径和绝对排他范围（rows、code_points 或 sections）；按绝对索引合并类型化记录，并按其代码点范围拼接 text_chunks。部分记录会保留其来源标识；可通过原始字段路径恢复省略的文本。元数据也可以分页。结构化字符串保持未转义状态；在切片后才进行呈现转义。规范化后的来源发生变化时会返回 stale_cursor；请在不带游标的情况下重新开始。来源完成游标与这些检索游标彼此独立。

---

courtlistener://reference/courts _资源

• Markdown 参考资料：22 个司法辖区代码（根据 courtlistener_lookup_courts 验证所用的集合生成）、常见法院 ID、搜索类型代码、已公布的免费层级速率限制，以及每周维护时段（太平洋时间周四 21:00–23:59）
• 静态内容，可公开缓存 24 小时

---

courtlistener_research_topic _提示词

• 参数：必填的 topic；可选的 jurisdiction（例如 scotus 或 ca9 等法院 ID）；可选的 depth，可设为 overview（默认值，3–5 个关键案例）或 deep（增加引文网络遍历和法官查询）
• 返回一条用户消息，其中列出研究工作流和发现模板：关键案例、判例轨迹、研究空白

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔的身份验证（none / jwt / oauth）、可切换的存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 追踪的结构化日志记录。

CourtListener 专属功能：

• CourtListener REST API v4：搜索、意见和集群、案卷和条目、当事人和律师、人员和职位、法院、音频、财务披露以及引证查询
• 整个进程共用一个请求队列，并按照 COURTLISTENER_RATE_LIMIT_PER_MINUTE 和 COURTLISTENER_RATE_LIMIT_PER_HOUR 控制请求速率，因此突发请求会等待，而不会失败；收到 429 时，队列会暂停所有等待中的调用；Retry-After 会在 45 秒的等待时限内得到遵守
• 每次调用的请求开销：大多数工具为 1；courtlistener_get_docket 为 2；courtlistener_get_parties 和 courtlistener_get_judge 为 2 或更多（每多一页较长的名册或履历就增加 1）；courtlistener_get_opinion 和 courtlistener_get_citations 为 3（意见变体每多一页就增加 1）；courtlistener_lookup_citation 则会产生查询请求，以及最多 max_court_lookups 个案卷请求
• 对无法成功的输入（空 q、格式错误的日期、超过 64,000 个字符的引证、未知的口头辩论章节），会在消耗请求前拒绝

面向 Agent 的输出：

• 可串联的 ID：凡是可供后续调用使用的地方，都会显示 cluster_id、docket_id、person_id、audio_id 和 disclosure_id，字段说明中会注明接受这些 ID 的工具
• 类型化的速率限制错误：返回 reason: "rate_limited"，并以秒为单位提供 retryAfter；无论是 CourtListener 返回 429，还是队列在发送前放弃请求，都会报告此错误；后一种情况下，消息会说明未消耗请求
• 有界检索：意见、音频和披露工具会保留较小的完整响应，并通过概览和可恢复的类型化分页流式传输过大的所选记录，且不会截断源文本
• 内联覆盖范围说明：RECAP 的 coverage_note、引证查询中的 court_resolution、职位历史记录中的 truncated，以及页面局部筛选导致当前页结果为空但后续仍有页面时的提示

开始使用

公共托管实例

https://courtlistener.caseyjhand.com/mcp 提供公共实例，无需安装。将任意 MCP 客户端指向该地址，并使用 Streamable HTTP：

{
  "mcpServers": {
    "courtlistener-mcp-server": {
      "type": "streamable-http",
      "url": "https://courtlistener.caseyjhand.com/mcp"
    }
  }
}

自托管 / 本地运行

将以下内容添加到 MCP 客户端配置文件中。在 CourtListener 账户设置中生成免费的 API 令牌。

{
  "mcpServers": {
    "courtlistener-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/courtlistener-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "COURTLISTENER_API_TOKEN": "your-api-token"
      }
    }
  }
}

或者使用 npx（无需 Bun）：

{
  "mcpServers": {
    "courtlistener-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/courtlistener-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "COURTLISTENER_API_TOKEN": "your-api-token"
      }
    }
  }
}

或者使用 Docker：

{
  "mcpServers": {
    "courtlistener-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "COURTLISTENER_API_TOKEN=your-api-token",
        "ghcr.io/cyanheads/courtlistener-mcp-server:latest"
      ]
    }
  }
}

使用 Streamable HTTP 时，设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 COURTLISTENER_API_TOKEN=... bun run start:http
# Server listens at http://localhost:3010/mcp

前置条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 一个免费账户的 CourtListener API 令牌，可在 courtlistener.com 获取。公布的免费层级限制为每分钟 5 个请求、每小时 50 个请求、每天 125 个请求；实际限制因令牌层级而异，Free Law Project 会员资格可提高限额。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/courtlistener-mcp-server.git

2. 进入目录：

cd courtlistener-mcp-server

3. 安装依赖项：

bun install

4. 配置环境：

cp .env.example .env
# edit .env and set COURTLISTENER_API_TOKEN

配置

变量	描述	默认值
COURTLISTENER_API_TOKEN	必填。 CourtListener 账户设置中的 API 令牌。	—
COURTLISTENER_BASE_URL	API 基础 URL 覆盖值。	https://www.courtlistener.com/api/rest/v4
COURTLISTENER_RATE_LIMIT_PER_MINUTE	服务每滚动分钟启动的请求数。超出后，请求会排队；约 45 秒内无法启动的请求会失败，并显示重置时间。可提高此值以匹配更高的令牌等级。	5
COURTLISTENER_RATE_LIMIT_PER_HOUR	服务每滚动小时启动的请求数。	50
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http。	stdio
MCP_HTTP_PORT	HTTP 服务端口。	3010
MCP_SESSION_MODE	HTTP 会话模式：stateless、stateful 或 auto。服务声明为 stateless；设置此变量可覆盖该声明。	stateless
MCP_AUTH_MODE	身份验证方式：none、jwt 或 oauth。	none
MCP_LOG_LEVEL	日志级别（debug、info、warning、error 等）。	info
LOGS_DIR	日志文件目录（仅 Node.js）。	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端：in-memory、filesystem、supabase、cloudflare-kv/r2/d1。	in-memory
OTEL_ENABLED	启用 OpenTelemetry。	false
OTEL_EXPORTER_OTLP_ENDPOINT	跟踪和指标的基础端点；会追加 /v1/traces 和 /v1/metrics。未设置端点时，两者均不会导出。	—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINT	用于脱敏 OTLP 日志的显式端点；基础端点不会启用日志导出。	—
LOG_TOOL_FAILURE_PAYLOADS	记录失败调用的输入和结果，并按键进行脱敏。	false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES	每个已记录的失败调用负载的大小上限。	16384

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t courtlistener-mcp-server .
docker run --rm -e COURTLISTENER_API_TOKEN=your-token -p 3010:3010 courtlistener-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/courtlistener-mcp-server。默认会安装 OpenTelemetry 对等依赖项——构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖项。

项目结构

目录	用途
src/index.ts	createApp() 入口：注册工具、资源和提示词，并初始化服务。
src/config	使用 Zod 解析并验证服务专属环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。共 14 个工具，涵盖意见、引文、案卷、当事方、法官、法院、口头辩论和财务披露。
src/mcp-server/resources	资源定义（*.resource.ts）。法院参考资源。
src/mcp-server/prompts	提示词定义（*.prompt.ts）。法律研究提示词。
src/services/courtlistener	CourtListener API 客户端（请求节流、重试、错误分类）、代码表和随附的法院快照（运行 bun run courts:snapshot 可重新生成）。
tests/	与 src/ 结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简要概述：

• 处理器抛出异常，框架负责捕获——工具逻辑中不要使用 try/catch
• 使用 ctx.log 记录请求范围内的日志，使用 ctx.state 进行租户范围内的存储
• 通过在 src/index.ts 中导入新工具、资源和提示词，并将其添加到 createApp({ tools, resources, prompts }) 数组中完成注册
• 封装 CourtListener API 调用：验证原始数据 → 规范化为领域类型 → 返回输出架构；绝不编造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。