CourtListener

CourtListener MCP 服务

一个 Model Context Protocol 服务，让 AI 助手能够访问 CourtListener 法律数据库（美国联邦和州法院判决、案卷、RECAP 文件、PACER 数据、口头辩论、 法官），以及通过官方 CourtListener API v4 访问 《联邦法规汇编》。

可与 Claude Desktop、Claude Code、Cursor、VS Code、Windsurf、ChatGPT Desktop 或任何兼容 MCP 的客户端配合使用。

Forked from Travis-Prall/court-listener-mcp。此分支新增了托管端点、自带密钥（BYOK）身份验证、/health 路由、强化版 Dockerfile、完整的 eCFR（联邦法规）工具套件、游标分页、按客户端限流，以及只读工具注释。详情请参阅变更日志。

何时使用此服务，而非官方服务

Free Law Project（CourtListener 的运营方）托管了官方 MCP 服务， 地址为 https://mcp.courtlistener.com/（采用 OAuth 身份验证，只需拥有任意 CourtListener 账户即可免费使用）—— 请参阅他们的公告。 如果你需要 OAuth 和最全面的 CourtListener 覆盖范围，请优先使用官方服务。如果你需要**《联邦法规汇编》（eCFR）工具**（官方服务没有这类工具）、简单的 BYOK 标头身份验证（无需繁琐的 OAuth 流程），或可自托管/可嵌入的 Python 服务，请使用此服务。两者相辅相成。

使用托管端点（无需安装）

Vaquill 团队为社区运行一个公开实例：

https://courtlistener-mcp.vaquill.ai/mcp/

你需要自备免费的 CourtListener 令牌，可从 courtlistener.com/help/api/rest/ 获取； 服务会转发该令牌。我们绝不会查看或存储你的密钥。

Claude Desktop / Claude Code

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "courtlistener": {
      "url": "https://courtlistener-mcp.vaquill.ai/mcp/",
      "headers": {
        "X-CourtListener-Token": "YOUR_COURTLISTENER_TOKEN"
      }
    }
  }
}

Cursor

.cursor/mcp.json：

{
  "mcpServers": {
    "courtlistener": {
      "url": "https://courtlistener-mcp.vaquill.ai/mcp/",
      "headers": { "X-CourtListener-Token": "YOUR_COURTLISTENER_TOKEN" }
    }
  }
}

VS Code（GitHub Copilot Chat）

.vscode/mcp.json：

{
  "servers": {
    "courtlistener": {
      "type": "http",
      "url": "https://courtlistener-mcp.vaquill.ai/mcp/",
      "headers": { "X-CourtListener-Token": "YOUR_COURTLISTENER_TOKEN" }
    }
  }
}

Claude Web（自定义连接器）

设置 → 连接器 → 添加自定义连接器 → 粘贴 URL，并将 X-CourtListener-Token 添加为标头。仅限工作区所有者使用。

Windsurf、Continue 等

任何支持带自定义标头的 MCP 可流式传输 HTTP 的客户端都可使用。 对于仅支持 stdio 的客户端，请在本地运行服务（见下文），或使用 mcp-remote 进行代理。

工具

共 34 个工具，分为 4 组（每组都有命名空间）。全部为只读工具。

分组	工具
搜索（CourtListener）	search_opinions、search_dockets、search_dockets_with_documents、search_recap_documents、search_audio、search_people
获取（CourtListener）	get_opinion、get_docket、get_audio、get_court、get_person、get_cluster
引用	citation_lookup_citation、citation_batch_lookup_citations、citation_verify_citation_format、citation_parse_citation_with_citeurl、citation_extract_citations_from_text、citation_enhanced_citation_lookup
eCFR（联邦法规）	ecfr_list_titles、ecfr_get_title_versions、ecfr_get_title_structure、ecfr_get_ancestry、ecfr_get_source_xml、ecfr_list_agencies、ecfr_list_all_corrections、ecfr_list_corrections_by_title、ecfr_search_regulations、ecfr_get_search_count、ecfr_get_search_summary、ecfr_get_title_search_counts、ecfr_get_daily_search_counts、ecfr_get_hierarchy_search_counts、ecfr_get_search_suggestions
系统	status

搜索工具接受 cursor 参数，并返回用于分页的 next_cursor。 完整参数详情请参阅 app/README.md。

身份验证

按优先级排序的两种模式：

1. 每个请求都携带请求头（BYOK） — 托管式／共享部署的首选方式。 在每个 MCP 请求中发送用户的 CourtListener 密钥：
   • X-CourtListener-Token: <key>（首选），或
   • Authorization: Token <key>（CourtListener 原生方案——仅当 MCP 服务本身未通过 Authorization 进行访问控制时才可用）。
2. 服务端环境变量回退 — 在服务端设置 COURT_LISTENER_API_KEY。 当未提供每请求请求头时使用。在公共实例中请不要设置，以强制使用 BYOK，并避免消耗运营方的配额。

如果两者均未提供，工具会返回带有明确提示的 ValueError。

自托管

Docker

git clone https://github.com/Vaquill-AI/courtlistener-mcp.git
cd courtlistener-mcp
cp .env.example .env  # optionally set COURT_LISTENER_API_KEY for single-tenant
docker compose up -d
# server at http://localhost:8000/mcp/

Python (uv)

uv sync
uv run python -m app --transport http

Stdio（本地 CLI 集成）

uv run python -m app --transport stdio

添加到 Claude Desktop：

{
  "mcpServers": {
    "courtlistener-local": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/courtlistener-mcp", "python", "-m", "app", "--transport", "stdio"],
      "env": { "COURT_LISTENER_API_KEY": "your_token" }
    }
  }
}

配置

变量	必需	默认值	说明
COURT_LISTENER_API_KEY	可选*	—	未提供每请求请求头时使用的回退值。在公共服务上请不要设置。
COURTLISTENER_BASE_URL	否	https://www.courtlistener.com/api/rest/v4/
COURTLISTENER_TIMEOUT	否	30	秒
MCP_TRANSPORT	否	stdio	stdio | http | sse
MCP_PORT	否	8000	仅适用于 http/sse
HOST	否	0.0.0.0	仅适用于 http/sse
ECFR_BASE_URL	否	https://www.ecfr.gov	eCFR API 基础 URL（无需密钥）
RATE_LIMIT_ENABLED	否	true	MCP 客户端级别的速率限制
RATE_LIMIT_RPS	否	15	每个客户端每秒的最大请求数
RATE_LIMIT_BURST	否	40	每个客户端的突发容量

* 仅在不使用 BYOK 的单租户模式下运行时必需。

健康检查

curl https://courtlistener-mcp.vaquill.ai/health
# {"status":"healthy","service":"courtlistener-mcp","version":"..."}

开发

uv sync --dev
uv run pytest
uv run ruff format . && uv run ruff check .
uv run mypy app/

更新日志

0.2.0

• 新增完整的 eCFR（联邦法规）工具套件（15 个工具）：标题、结构、版本、沿革、源 XML、机构、更正，以及法规全文搜索和分析。这是本项目相较于仅支持 CourtListener 的服务的差异化优势。
• 修复验证崩溃问题：可选搜索筛选器现在可接受空值（str | None），因此客户端显式发送 JSON null 时不再触发 ValidationError（此前会导致 search_dockets / search_recap_documents 出错）。
• 真正的分页：移除了无效的 hit 参数；搜索工具现在会遵循 limit，并提供 next_cursor 令牌和输入参数 cursor。
• 所有工具均添加只读工具注解（改善客户端体验，无需显示写入提示）。
• 添加按客户端进行速率限制的中间件（可配置，默认开启）。
• 将 import_server 迁移为 mount（FastMCP 3），修复 API 密钥环境变量别名，更新项目元数据，并使测试套件全部通过（单元测试使用模拟；实时 API 测试需通过 RUN_INTEGRATION=1 启用）。

鸣谢与许可

• 原始实现：Travis-Prall/court-listener-mcp
• 托管方：Vaquill — courtlistener-mcp.vaquill.ai
• 许可：MIT（参见 LICENSE）

CourtListener 数据由 Free Law Project 提供，具体条款以其规定为准。eCFR 数据来自 ecfr.gov。

社区

有疑问、想法，或想参与贡献？欢迎加入 Vaquill 的 Discord 社区。