clio-mcp

Clio MCP 服务：将 Claude 连接到 Clio Practice Management

由 Oktopeak 构建：为律所提供 AI 转型与自动化

为法律和医疗健康企业提供数字化转型服务。 我们构建 AI 集成、工作流自动化和由贵所完全拥有的定制软件，包括此连接器。→ 预约 30 分钟通话

用 26 秒了解此连接器如何服务整个律所：在您自己的云端运行，每个人使用自己的 Clio 登录账号登录，统一审计日志，每月构建一项自动化，费用为每月固定 300 美元。观看视频。

开源的 Model Context Protocol（MCP）连接器，可让 Claude 从 Clio 实时读取数据（案件、自定义字段、备注、联系人、文档、文件夹、任务、日历和账单），无需将客户信息复制到聊天窗口。专为重视律师与客户保密特权、遵守 ABA Opinion 512，以及让 AI 工作流留在现有律所管理系统中的律所打造。

简而言之： 通过 stdio 和 HTTP/SSE 传输协议向 Claude 提供 37 个 Clio 工具。记录审计日志，符合 ABA Opinion 512。OAuth 令牌使用 AES-256-GCM 静态加密。默认仅在本地运行：您自行注册 Clio 开发者应用，中间没有中继服务。另有适用于 Clio App Directory 的独立一键“上架”版本，使用精简的仅登录代理，详见上架／一键安装版本。采用 MIT 许可证，永久免费。

适用对象： 律所 IT、法律运营团队、积极拥抱技术的合伙人，以及法律科技公司的工程师。只要能按步骤完成五步终端安装，就能使用。

提示

不是开发者？也没关系。

以下 README 假设读者熟悉编辑 JSON 配置文件。如果您或您的团队不熟悉，我们可以为律所部署：限定范围的凭据、接入审计日志、定制一项工作流，并提供培训。我们也计划在 v0.2 推出更简单的一键命令安装程序。

→ 整个律所使用？选择律所方案：每月 300 美元。 部署在您自己的云端，每位律师使用自己的账号登录，统一审计日志，每月为您构建一项自动化，不收设置费，随时可取消。→ oktopeak.com/firm-plan/，或预约 30 分钟通话

快速跳转： 演示 · 设置 · 可用工具 · 导出整个账号 · 安全与合规 · 需要我们为您部署？

---

演示

观看 Claude 在不到一分钟内从 Clio 提取实时数据（案件、联系人、任务），而无需将客户信息复制到聊天中。

▶  在 YouTube 上观看 60 秒演示

---

为使用 Claude + Clio 构建工作流的律所提供设置技巧和 ABA Opinion 512 合规更新。

→ 订阅 Oktopeak Builder Notes。邮件简短，可轻松退订。

---

2.5.0 新功能：导出整个账户

npx @oktopeak/clio-mcp export --out <folder> 会将所有事项、联系人、笔记、任务、日历条目、工时记录、费用、账单和文档从 Clio 复制到你自己的电脑上。此操作为只读，并在你自己的 Clio 应用下进行。请先运行 npx @oktopeak/clio-mcp auth。请参阅导出整个账户。

升级到 2.2.0

如果你在 2026 年 9 月之前安装了此工具，那么你使用的是 2.0.1。升级有一个重要原因，值得在此明确说明，而不是埋在更新日志里。

2.0.1 会将客户数据写入审计日志。 联系人搜索查询、笔记主题、事项描述和自定义字段值都会原样记录在 ~/.clio-mcp/audit.log 中。该日志是一个不会轮换的普通文件。在 2.2.0 中，审计条目仅包含 ID、数量、日期和页码令牌；这由允许列表而非拒绝列表强制实施，并配有一项测试，确保任何工具都不会再次开始记录内容。

npm install -g @oktopeak/[email protected]   # or just restart Claude Desktop if you use npx

你现有的 ~/.clio-mcp/audit.log 仍包含旧版本写入的所有内容。建议你先查看日志，再决定如何处理。

此外，自 2.0.1 以来还新增了：事项和联系人的自定义字段与笔记、文件夹工具、事项关系、一次调用即可汇总未结事项的活动情况、配置级别的 READ_ONLY 模式，以及读取时的完整分页，避免因答案不完整而出错。请参阅 CHANGELOG.md。

合规与安全

之所以设立本节，是因为评估 AI 工具的律师事务所提出了恰当的问题。以下是直接答复。

ABA 正式意见 512：AI 与专业能力

ABA 意见 512（2023 年）要求使用 AI 工具的律师了解这些工具的工作原理、监督其输出，并维护客户信息的机密性。本连接器在设计时考虑了这些义务：

• 审计日志。 每次工具调用（每当 Claude 代表你查询 Clio 时）都会追加到本地日志文件 ~/.clio-mcp/audit.log 中。每条记录都包含时间戳、调用的工具、传入的参数、调用是否成功以及 Clio 用户 ID。日志存储在你的计算机上，而非任何云服务中。日志只能追加，软件不会清除日志，因此律所可以保留 AI 发起的数据访问完整记录。

• 连接器不保留数据。 连接器本身不会存储事项数据、客户姓名或任何 Clio 内容。它会从 API 获取数据并将结果传递给 Claude。它唯一会在本地持久保存的是你的身份验证令牌，并且该令牌经过加密（见下文）。单独的 export 命令是唯一例外，这是有意设计的：它会将 Clio 数据的本地副本写入你选择的文件夹，其他操作都不会这样做。

• 12 个写入工具，全部记录，全部可选。 连接器可以创建事项、自定义字段、笔记、任务、文件夹、日历条目、工时记录和活动，更新事项和任务，完成任务，以及上传文档。它绝不会删除任何内容，也不会操作联系人或计费记录。每项写入操作都会记录在审计日志中；READ_ONLY=true 会从服务中完全移除全部 12 个写入工具（见只读模式），因此律所可以先启用读取权限，决定好后再开启写入权限。

令牌安全：静态加密

你的 OAuth 凭据绝不会以明文存储。完成身份验证后，连接器会使用与金融机构相同的标准 AES-256-GCM 加密你的访问令牌和刷新令牌，并将密文写入 ~/.clio-mcp/tokens.enc。加密密钥会在首次运行时自动生成，并存储在操作系统密钥链中（macOS Keychain、Windows Credential Manager 或 Linux Secret Service），绝不会以明文形式存储在文件系统中。

如果有人获得了令牌文件，但没有密钥，就无法读取其中的内容。

OAuth 2.0：不存储密码

身份验证使用 Clio 标准的 OAuth 2.0 流程。你通过浏览器在 Clio 自己的登录页面登录。此连接器不会查看或处理你的 Clio 密码。每次身份验证请求都会通过加密的 state 参数实现 CSRF 防护。

本地优先架构

连接器完全在你的设备上运行。没有 Clio MCP 云服务、没有中继服务，也没有第三方介入。你的 Clio API 流量会从你的设备直接传输到 Clio 的服务器。

以下默认设置适用此情况，你需要在其中注册自己的 Clio 开发者应用。单击式“已上架”安装方式（下一节）是唯一例外，且仅在登录步骤中例外。

已上架／单击式安装方式（App Directory）

如果你是通过 Clio App Directory 的单击式安装来安装此连接器，而不是注册自己的 Clio 开发者应用，那么你使用的是已上架版本。该版本使用一个由 Oktopeak 所有、供所有安装律所共用的 Clio 应用，而不是每家律所各自使用一个应用。这意味着应用的 client_secret 无法分发到你的设备上——它只存放在 Oktopeak 运营的小型托管令牌代理服务中。

具体而言，这会带来以下变化： 案件数据会在你的设备与 Clio 之间直接传输；只有登录握手会经过我们的令牌服务。每次工具调用——案件、联系人、文档、任务、日历、账单等所有内容——仍会像上述 BYOC 设置一样，从你的设备直接发送到 Clio API。代理服务不会查看、存储或记录其中任何数据；它只会在完成 OAuth 登录所需的几秒钟内参与处理（令牌刷新时也会短暂参与）。它不会持久存储任何内容——令牌和会话数据都不会在这次握手结束后保留。

供安全审查人员查阅的完整数据流文档（包括时序图，以及代理服务会持久保存和绝不会持久保存的内容）位于令牌代理服务的代码仓库中：docs/DATA_FLOW.md。

其余部分——本地 AES-256-GCM 令牌加密、审计日志和 37 个工具——都与 BYOC 设置完全相同。请注意，Clio 的 OAuth 不支持按登录请求更精简的权限范围；令牌所持有的权限取决于连接的 Clio 应用在 Clio Developer Portal 中注册时获授的权限。对于已上架应用，其注册权限已限制为 37 个工具所需的最低权限集——这与自行注册应用以使用 BYOC 设置时应遵循的原则相同。有关最终生成的 Claude Desktop 配置，请参见下文的 Option C。

---

信任模型

在安装用于敏感法律工作的 AI 工具之前，从业者应先提出以下三个问题。

我们应该使用哪个 Claude 层级？

该连接器保护 Clio 与 Claude 之间的传输安全。它不会改变 Claude 本身在数据进入对话后对数据的处理方式。Claude 的数据处理方式取决于你使用的层级，而不是这个连接器。

• 具有零数据保留 （ZDR） 的 Anthropic API：无训练、无保留条款，在 Anthropic API 的组织级别启用。小型律所也可以获得；它并非大型企业合同专属。对于任何涉及受特权保护的客户数据的工作，这是我们推荐的配置。
• Claude Enterprise / Team：明确的无训练保证，并可选择启用 ZDR。这是获得上述配置的一种方式，适合希望使用托管工作区而非 API 集成的律所。Claude Enterprise 是其中一种选择，但不是唯一选择。
• Claude Pro / Max（消费者版）：Anthropic 默认不会使用消费者聊天数据进行训练，出于安全目的的人工审查也有限。可用于非特权内容的探索。在处理客户事务数据时，它不能替代零数据保留部署。

如果你在律所部署此连接器，请将其与零数据保留配置搭配使用（组织级别的具有 ZDR 的 Anthropic API，或具有 ZDR 的 Claude Enterprise）。如果你是个人律师，在个人数据或非特权数据上进行测试，Claude Pro 在测试阶段是合理的，但不应成为客户工作的长期配置。

关于模型选择有一个注意事项：无保留默认设置取决于模型。最新且能力最强的模型可能需要保留并选择加入审查，因此请有意固定模型，并在每次供应商发布时重新检查保留条款。

访问与保留：大多数评估遗漏的区别

一个常见的假设是，日志记录等于合规：如果有关于访问了什么的记录，律所就受到覆盖。这把两件不同的事情混为一谈，而它们之间的差距正是受特权保护内容被暴露的地方。

• 保留是指请求之后数据会发生什么：答案返回后，它是否会持续存在于训练集、供应商日志或任何系统中。
• 访问是指模型是否曾经看到过事务内容，即使是短暂地、在传输中、仅仅为了生成答案。

对于受特权保护的事务内容，**访问就是暴露。**受特权保护的内容进入对话的那一刻，模型就已经处理了它，无论之后是否保留任何内容。无保留和无训练保证限制的是数据之后会发生什么；它们不能撤销数据曾被看到这一事实，而律所的审计日志只记录访问发生过，并不记录该访问是被允许的。

这就是为什么层级选择对于受特权保护的工作不是可选项。对于任何涉及受特权保护事务内容的内容，零数据保留是唯一干净的答案，无论你是在组织级别通过 Anthropic API 获得它，还是通过 Claude Enterprise 获得：在这种配置下，内容依据合同性的无训练、无保留条款处理，而不是消费者条款。如果事务受特权保护，而你未使用 ZDR 配置（或本地模型，见下文），请假设该内容已依据你律所尚未审查过的条款被暴露。

连接器自身的无保留姿态（除加密令牌外不存储任何内容）仅覆盖传输层。它并未说明一旦内容进入对话，模型层级会如何处理该内容。第二个问题正是本节要回答的问题，也是你律所在受特权保护的数据到达 Claude 之前必须回答的问题。

供应链信任（npm 包）

此连接器以 @oktopeak/clio-mcp 的名称发布在 npm 上。与所有 npm 包一样，维护者可随时更新已发布的版本。请遵循标准的安全实践：

• 在生产环境中锁定版本。 使用确切版本，例如 @oktopeak/[email protected]（package.json 中的当前版本），不要使用 ^2.0.0 这样的版本范围。升级前请先审计。
• 审查差异。 每个版本都对应 GitHub 上的一个已标记提交。在将新版本部署到整个律所之前，请核实更改。
• 从源代码构建。 如果律所要求这样做，请克隆仓库、审计代码，并使用自行构建的产物运行。我们不会将任何功能限制在 npm 发行版中。
• 维护者。 由 Oktopeak 发布。这是一支公开团队，拥有公开提交记录和公开的 npm 发布者账号，并非匿名。我们通过 [email protected] 回复安全问题报告。

哪些内容已加密，哪些没有

为避免常见的误解：

• OAuth 令牌（你的 Clio 访问令牌和刷新令牌）在 ~/.clio-mcp/tokens.enc 中以 AES-256-GCM 加密后静态存储。没有加密密钥就无法读取。
• 加密密钥本身会在首次运行时自动生成，并存储在操作系统的密钥链中（macOS Keychain、Windows Credential Manager 或 Linux Secret Service）。密钥不会以明文形式写入文件系统。对于没有密钥链的 CI／无头安装，你可以在环境中将 ENCRYPTION_KEY 设置为一个 64 位十六进制字符串，以覆盖此设置。
• ~/.clio-mcp/audit.log 中的审计日志条目未加密。日志包含元数据（时间戳、工具名称、已隐去机密信息的参数），不包含 Clio 内容。
• export 写入的导出文件夹未经过连接器加密。其中以明文形式保存你的 Clio 数据，包括 checkpoint/ 中的客户名称。请将其存放在加密磁盘上。

---

使用本地模型运行（不经过第三方处理方）

在 United States v. Heppner 案的 SDNY 裁决（2026 年 2 月）认定消费版 Claude 不受律师—客户保密特权保护后，一些律所希望部署完全不经过第三方 AI 处理方的方案：模型推理完全在律所自己的硬件上运行。

此连接器开箱即支持这种方案。MCP 是一种协议，并非 Claude 专属功能。与 Claude Desktop 通信的同一个连接器也可以与以下对象通信：

• LM Studio，在本地运行 Llama 4 70B／DeepSeek V4／Mistral Large（推荐的主要方案）
• Continue.dev + Ollama + 一个桥接工具（mcphost 或 ollama-mcp-bridge）
• 任何其他兼容 MCP 的客户端

完整部署指南和示例配置见 docs/privilege-stack/。有关战略背景（此方案何时优于 Claude Enterprise、硬件规格、验证步骤），请参阅我们的 Privilege Stack 博文。

---

可以做什么

连接后，你可以向 Claude 提出以下问题：

事项

• “显示 Acme Corp 的所有未结事项”
• “事项 2024-0042 的状态如何？”
• “列出我上个季度待处理的事项”
• “为 Acme Corp 创建新事项：诉讼，负责人律师 John Smith”

联系人

• “查找 Jane Smith 的联系信息”
• “客户 ID 8821 的电子邮件地址和电话号码是什么？”
• “显示所有匹配‘Acme’的联系人，如果还有更多结果，请获取下一页”

文档

• “列出事项 4821 的所有文档”
• “获取文档 9934 的下载链接”
• “查找所有事项中名为‘retainer’的文档”

任务

• “事项 4821 本周有哪些到期任务？”
• “显示所有未完成的高优先级任务”
• “在事项 4821 中创建一项任务：周五前提交动议，优先级为高”

备注

• “在事项 4821 中添加备注：已完成初次咨询，客户确认了委托关系”
• “在此事项中创建一条备注，总结今天与客户的通话”

日历

• “4 月 28 日至 5 月 2 日期间我安排了什么？”
• “列出下周的所有日历条目”
• “显示我可用的所有日历”
• “在 6 月 10 日上午 9 点为事项 4821 添加庭审安排”

工时条目

• “本月事项 4821 记录了多少小时？”
• “显示 4 月 1 日至 4 月 30 日之间的所有工时条目”

账单

• “事项 4821 的未结余额是多少？”
• “此事项最近一次开具发票是什么时候？”

用户

• “列出律所的所有律师”
• “Jane Smith 的用户 ID 是什么？”
• “显示所有员工”

连接器会在每次请求时从 Clio 检索实时数据。AI 不会缓存或存储任何内容。

---

要求

开始之前，请确保你具备：

• Node.js 20 或更高版本：nodejs.org/en/download
• Claude Desktop：claude.ai/download
• Clio 账户，且有权创建开发者应用（如不确定，请咨询 Clio 管理员）

---

设置

**共 5 个步骤。首次设置需 10-15 分钟。**你将注册一个 Clio Developer App，在 Claude Desktop 配置中添加一个 JSON 块，并执行 OAuth 登录。加密密钥会自动生成；无需手动处理密钥。

在生产环境中运行之前，请先阅读上文的合规与安全和信任模型部分。如果要为律所部署，请将连接器与零数据保留配置搭配使用（组织级别启用 ZDR 的 Anthropic API，或 Claude Enterprise）；请参阅上文的“我们应该使用哪个 Claude 版本？”。

步骤 1：克隆并构建

打开终端并运行：

git clone https://github.com/oktopeak/clio-mcp.git
cd clio-mcp
npm install
npm run build

记下刚刚克隆的文件夹的完整路径；步骤 3 中会用到。

# On Mac/Linux, print the full path:
pwd

# Example output: /Users/yourname/clio-mcp

步骤 2：创建 Clio API 应用

1. 前往 developers.clio.com，并使用 Clio 账号登录
2. 点击 Developer Apps → Add
3. 为应用命名（例如，Claude Connector）
4. 将重定向 URI 设置为：http://127.0.0.1:5678/callback
5. 保存应用
6. 复制 Client ID 和 Client Secret；下一步会用到

步骤 3：配置 Claude Desktop

从 v2.0.0 起，连接器支持两种传输方式：stdio（连接器作为 Claude Desktop 的子进程运行，适用于单用户）和 HTTP/SSE（连接器作为独立服务运行，支持多个会话和远程访问）。请选择一种。

打开 Claude Desktop 配置文件：

• Mac： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

方案 A：stdio（最简单，单用户）

在 "mcpServers" 部分内添加以下代码块，并将占位符值替换为你自己的值：

{
  "mcpServers": {
    "clio": {
      "command": "node",
      "args": ["/FULL/PATH/TO/clio-mcp/build/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "CLIO_CLIENT_ID": "your_client_id",
        "CLIO_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

将 /FULL/PATH/TO/clio-mcp 替换为你在第 1 步中记录的路径（例如 /Users/yourname/clio-mcp）。必须设置 TRANSPORT=stdio，因为该连接器在 v2.0.0 中默认使用 HTTP 模式。

方案 B：HTTP/SSE（独立服务，多会话）

将连接器作为长期运行的服务启动。在 HTTP 模式下必须使用 API 密钥。 除非将 MCP_API_KEY 设置为至少 24 个字符的密钥，否则服务将拒绝启动。请先生成一个密钥，然后启动服务。在终端中，从 clio-mcp 目录执行：

# Generate a key once and keep it somewhere safe
openssl rand -hex 32

TRANSPORT=http MCP_BASE_URL=http://127.0.0.1:3000 MCP_API_KEY=<the key you generated> \
CLIO_CLIENT_ID=your_client_id CLIO_CLIENT_SECRET=your_client_secret \
node build/index.js

然后通过 mcp-remote 桥接将 Claude Desktop 指向它，并将同一个密钥作为 bearer token 传入。（mcp-remote 推荐使用 ${AUTH_HEADER} 形式，因为 Claude Desktop 无法可靠地处理 args 中的空格。）

{
  "mcpServers": {
    "clio": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:3000/mcp", "--header", "Authorization:${AUTH_HEADER}"],
      "env": { "AUTH_HEADER": "Bearer <the key you generated>" }
    }
  }
}

所有到达 MCP 服务的路由在没有密钥时都会返回 401 Unauthorized：/mcp 上的所有方法（POST、GET/SSE 流、DELETE）以及任何未知路径。只有 /health 和 OAuth 重定向目标 /oauth/callback 无需密钥即可访问，因为 Clio 的浏览器重定向无法携带 bearer token。

仅限本地开发： 如果你需要在自己的机器上运行不带密钥的 HTTP 服务，请设置 MCP_ALLOW_UNAUTHENTICATED=true。服务启动时会发出醒目的警告，并且所有路由都会开放。切勿在公共主机或其他人可以访问该端口的地方使用此设置；任何能够访问该端点的人都可以利用你的 Clio 访问权限来操作该连接器。

方案 C — 通过 Clio App Directory 一键安装

如果你是通过 Clio App Directory 安装的，则无需注册开发者应用，也无需处理 CLIO_CLIENT_SECRET —— 安装程序会为你完成配置。生成的配置使用 TOKEN_BROKER_URL 代替 CLIO_CLIENT_ID/CLIO_CLIENT_SECRET：

{
  "mcpServers": {
    "clio": {
      "command": "node",
      "args": ["/FULL/PATH/TO/clio-mcp/build/index.js"],
      "env": {
        "TRANSPORT": "stdio",
        "TOKEN_BROKER_URL": "https://broker.oktopeak.com"
      }
    }
  }
}

关于这会如何改变数据流，请参见上文的 上架 / 一键安装变体。

---

如果该文件中已经配置了其他 MCP 服务，请在最后一项后添加一个逗号，然后添加 "clio" 代码块。

使用 Clio EU、Australia 或 Canada？ 将 CLIO_REGION 设置为 eu、au 或 ca（默认为 us）。Clio 在创建账户时分配区域，该值必须与你的公司登录的 Clio 服务一致：app.clio.com（us）、eu.app.clio.com（eu）、au.app.clio.com（au）或 ca.app.clio.com（ca）。登录 Clio 后检查浏览器中的主机名，如果不确定，请联系 Clio 支持。完整表格请参见下文的 Clio 区域。

第 4 步：重启 Claude Desktop

完全退出 Claude Desktop，然后重新打开。

提示

使用 Windows？ 影响我们 MyCase MCP 安装的 Windows 特有问题同样也会影响 Clio MCP：Could not attach to MCP server（直接调用 npx）、UNABLE_TO_VERIFY_LEAF_SIGNATURE（企业杀毒软件的 SSL 检查）以及 OAuth 重定向端口不匹配。修复方法（cmd /c npx 包装、NODE_OPTIONS=--use-system-ca、端口匹配）记录在我们的配套安装指南中。

→ Windows 上的 MyCase MCP：我们希望存在过的安装指南，该指南是为 MyCase MCP 编写的，但其中的 Windows 修复方法同样适用于 Clio MCP。

第 5 步：通过 Clio 身份验证

在新的 Claude 对话中，输入：

authenticate with Clio

Claude 会在浏览器中打开 Clio 登录页面。照常登录。看到 "Authentication successful" 后，返回 Claude。现在已连接。

要确认一切正常运行，请输入：

check my Clio auth status

你应该会看到自己的 Clio 用户 ID 和令牌到期时间。

---

提示

不是负责编辑配置文件的人？

如果觉得以上五个步骤太繁琐，我们可以为你的律所部署：范围受限的 OAuth 凭据、接入你技术栈的审计日志、与你的团队共同设计一个自定义工作流，以及培训。大多数律师事务所发现，这种方式更快捷。

→ 整个律所都要用？Firm Plan：每月 $300。 在你自己的云中设置，每位律师使用各自的登录信息，每月为你构建一项自动化，无设置费，随时取消。→ oktopeak.com/firm-plan/，或预约 30 分钟的需求沟通电话

---

可用工具

Claude 会根据你的问题自动选择并调用这些工具。你无需按名称调用它们。

身份验证（3 个工具）

工具	功能
authenticate	在浏览器中打开 Clio 登录页面，并安全地保存你的凭据
auth_status	显示你当前是否已通过身份验证，以及会话何时到期
logout	清除这台机器上保存的凭据

案件（4 个工具）

工具	输入	功能
list_matters	status（open/pending/closed）、limit、page_token	列出案件，可选按状态筛选，并包含自定义字段值；返回包含 total_count、has_more 和 next_page_token 的分页封装
get_matter	matter_id	返回指定案件的完整详情，包括其 Maildrop 转发地址和自定义字段值
create_matter	client_id、description、status、open_date、practice_area_id、billable、responsible_attorney_id、originating_attorney_id、client_reference、custom_field_values	创建新案件；状态默认为 Open，可计费默认为 true
update_matter	matter_id，以及 create_matter 的任意可选字段	更新现有案件的一个或多个字段，包括阶段和自定义字段值

自定义字段（2 个工具）

工具	输入	功能
list_custom_fields	parent_type（Matter/Contact）、include_deleted	列出账户的自定义字段定义及其类型；对于选项列表字段，还会列出允许的选项。在读取或写入自定义字段前调用
create_custom_field	name、parent_type（Matter/Contact）、field_type、required、displayed、picklist_options	创建新的自定义字段定义。使用返回的 id 作为 create_matter / update_matter 中的 custom_field_id 来设置其值

案件阶段（1 个工具）

工具	输入	功能
list_matter_stages	practice_area_id	按执业领域和流程顺序列出账户的案件阶段（Pre-Suit、Discovery、Settlement 等）。设置 matter_stage_id 前请先调用。Clio 可以将工作流和任务列表关联到某个阶段；由 API 驱动的阶段变更是否会触发它们尚未验证，因此请先在一个案件上确认，再依赖此功能

联系人（2 个工具）

工具	输入	功能说明
search_contacts	query、limit、page_token	按姓名、电子邮件或公司搜索联系人；返回包含 total_count、has_more 和 next_page_token 的分页封装；传回令牌以获取下一页
get_contact	contact_id	返回指定联系人的完整详细信息，包括所有电子邮件、电话号码、地址和自定义字段值

关系（1 个工具）

工具	输入	功能说明
list_matter_relationships	matter_id、limit、page_token	列出与案件关联的联系人及其担任的角色（共同律师、专家、事实证人、对方律师）

文档（3 个工具）

工具	输入	功能说明
list_documents	matter_id、parent_id、query、limit、page_token	列出文档或进行全文搜索；必须提供 matter_id、parent_id 或 query 中的至少一项；返回包含 total_count、has_more 和 next_page_token 的分页封装
get_document	document_id	返回文档元数据和直接下载 URL
upload_document	file_path、matter_id、name、content_type	使用 Clio 的分段 S3 上传流程将本地文件上传到案件

文件夹（3 个工具）

工具	输入	功能说明
list_folders	matter_id、parent_id、query、limit、page_token	列出文件夹或进行全文搜索；必须提供 matter_id、parent_id 或 query 中的至少一项；返回包含 total_count、has_more 和 next_page_token 的分页封装
folder_exists	matter_id 或 parent_folder_id、name	检查是否已存在具有指定确切名称的文件夹；会完整遍历所有分页，且不依赖父级类型筛选，因此不会漏掉案件的文档根目录本身就是 Folder 节点的文件夹
create_folder	name、matter_id 或 parent_folder_id、if_not_exists	在案件的文档根目录下或现有文件夹中创建文件夹；请先调用 folder_exists 以避免重复创建

任务（4 个工具）

工具	输入	功能说明
list_tasks	matter_id、status（Pending/Complete/In Progress/In Review/Draft）、due_date_start、due_date_end、limit	列出任务，可选提供筛选条件
create_task	matter_id、name、description、priority（High/Normal/Low）、due_date、assignee_id	在案件中创建任务；优先级默认为 Normal
update_task	task_id、name、description、priority、due_date、status、assignee_id	更新现有任务的一个或多个字段
complete_task	task_id	将任务标记为已完成

日历（3 个工具）

工具	输入	功能说明
list_calendars	无	列出用户有权写入的日历；创建条目时，将返回的 id 用作 calendar_owner_id
list_calendar_entries	from、to、limit、page_token	列出指定日期范围内的日历条目（YYYY-MM-DD 或 YYYY-MM-DDTHH:MM）；返回包含 total_count、has_more 和 next_page_token 的分页封装
create_calendar_entry	summary、start_at、end_at、calendar_owner_id、description、all_day、matter_id、location、send_email_notification、attendee_ids	创建日历条目（听证会、截止日期、会议）；start_at/end_at 接受日期或日期时间

时间条目和费用（4 个工具）

工具	输入	功能
list_time_entries	matter_id、start_date、end_date、limit、page_token	按可选筛选条件列出可计费的时间条目；返回包含 total_count、has_more 和 next_page_token 的分页封装
list_expenses	matter_id、user_id、start_date、end_date、expense_type、limit、page_token	列出费用（默认类型为 ExpenseEntry；也可按需指定 HardCostEntry / SoftCostEntry），包含金额、数量和类别；使用相同的分页封装
log_time_entry	matter_id、date、quantity_in_hours、note、price、non_billable、no_charge、activity_description_id、user_id	在事项中创建新的可计费（或不可计费）时间条目
create_activity	type、date、matter_id、note、quantity_in_hours、price、non_billable、no_charge、activity_description_id、user_id、reference、tax_setting	创建任意 Clio 活动类型：TimeEntry、ExpenseEntry、HardCostEntry 或 SoftCostEntry

账单（1 个工具）

工具	输入	功能
get_billing_summary	matter_id	返回某事项的已开票总额、未付余额和最近发票日期

备注（2 个工具）

工具	输入	功能
create_note	matter_id、subject、body	在事项中创建备注；备注会显示在 Clio 的事项时间线上
list_notes	matter_id 或 contact_id、created_since、updated_since、limit、page_token	列出备注，包含主题、作者、备注自身的日期以及纯文本正文（富文本标记保存在 detail_html 中）

报告（1 个工具）

工具	输入	功能
matter_activity_summary	lookback_days、calendar_days_ahead、practice_area_id、stale_after_days、limit	一次调用即可获取每个未结事项的最后一条备注、最后一个时间条目、下一个日历条目、未结任务数以及距上次活动的天数，并按最不活跃的事项优先排列。它会在整个账户范围内各读取一次集合，因此开卷规模不会影响成本

用户（2 个工具）

工具	输入	功能
list_users	name、subscription_type（attorney/nonattorney）、enabled、limit、page_token	列出律所用户及其 ID；返回包含 total_count、has_more 和 next_page_token 的分页封装
get_user	user_id	按 ID 返回单个用户的详细信息

审计日志（1 个工具）

工具	输入	功能
export_audit_log	date_from、date_to、matter_id、limit、offset	导出用于律师协会审查和遵循 ABA Opinion 512 的审计日志条目。可按日期范围和事项筛选，并支持分页（默认每页 500 条，最多 1000 条）

---

导出整个账户

同一个软件包可以将 Clio 中的所有内容复制到你自己的电脑上：每个事项、联系人、备注、任务、日历条目、时间条目、费用和账单都会导出为数据文件，每份文档都会作为文件放入助理可以浏览的文件夹树中。你可以将它用作备份，也可以在取消服务前使用。它只会读取 Clio 中的数据，绝不会写入任何内容。

npx @oktopeak/clio-mcp auth
npx @oktopeak/clio-mcp export --out ./clio-export

auth 会打开浏览器、保存登录信息，并显示登录者及令牌到期时间。export 不会打开浏览器；如果没有保存的登录信息，它会停止运行并提示“run auth first”。这两个命令都需要与连接器相同的环境变量（CLIO_CLIENT_ID、CLIO_CLIENT_SECRET，以及在非 us 区域时使用的 CLIO_REGION）和 Node.js 20 或更高版本。使用 npx 时没有 .env 文件可供读取，因此请在 shell 中设置这些变量：

# macOS / Linux
export CLIO_CLIENT_ID=your_client_id CLIO_CLIENT_SECRET=your_client_secret CLIO_REGION=eu

# Windows PowerShell
$env:CLIO_CLIENT_ID = "your_client_id"
$env:CLIO_CLIENT_SECRET = Read-Host "Clio client secret"
$env:CLIO_REGION = "eu"

取消服务前请先导出。先运行 --dry-run：它只会统计记录和文档，并写入 REPORT.md，估算实际运行所需的时间和磁盘空间。

选项

选项	功能
--out <folder>	必填。文件夹必须为空或是之前导出的文件夹。
--since <date>	仅导出此日期之后更改的记录，前提是 Clio 支持此功能（见下文）。
--only <list>	以逗号分隔的记录类型，例如 matters,folders,documents。只有与 documents 一起指定时，才能指定 document_versions。
--no-documents	跳过文档及其文件。
--rate <n>	每秒请求数。默认为 0.8，最高为 10。Clio 每分钟允许约 50 次请求，因此高于约 0.8 的值会受到 Clio 限流。
--concurrency <n>	并行下载数。默认为 3，最高为 8。
--resume	在同一文件夹中继续之前的运行。
--dry-run	仅统计数量。只在文件夹中写入 REPORT.md，不写入其他内容。
--help	显示选项。

记录类型：matters、contacts、users、practice_areas、custom_fields、matter_stages、relationships、tasks、calendar_entries、notes、time_entries、expenses、bills、folders、documents。仅在 --only 中指定时可用：document_versions、communications、allocations、trust_line_items、bank_transactions。对于 Clio 拒绝提供的可选类型，会报告为“不可用”，而不是错误。

导出内容

clio-export/
  data/<type>.jsonl            raw records, one per line
  data/<type>.csv              the same records for Excel
  matters/<number> - <client>/ documents, mirroring the Clio folder structure
  checkpoint/                  where the export saves its place
  manifest.json
  errors.jsonl                 failures: record type, status code and kind only
  REPORT.md                    what was exported, what was not, and why

文档文件的名称格式为 <original name> [<document id>].<extension>，并已处理为适用于 Windows（不含非法字符、保留名称或过长路径）。原始名称和文件夹路径列在 data/documents.csv 中。每个文档的最新版本都会下载；其版本 ID 保存在数据中。指定 --only document_versions 还会将版本历史保存为数据。

Windows 无法存储的名称（如 CON 等保留名称、末尾带点或空格的名称、含禁用字符的名称）也会在导出时处理：CON.txt 会变为 _CON [id].txt。在 EU 测试账户上的实际测试中，Clio 拒绝上传以点结尾的文件名，因此导出的文档中不应出现此类名称。

空文件夹会列在 folders.jsonl 中，但不会在磁盘上创建；文件夹树中只会显示包含文档的文件夹。

CSV 文件可在 Excel 中正常打开。以 =、+、- 或 @ 开头的文本会在 CSV 中添加前导单引号，以防 Excel 将其作为公式运行；数字不会被更改，.jsonl 文件始终保留精确值。

不包含的内容

• 分类账报告（信托分类账、客户分类账、账单历史记录、应收账款、进行中的工作）。指定 --only ledger_reports 时会说明这一点，但不会导出任何内容。
• Clio 渲染的账单 PDF。账单会作为数据导出。
• 原始电子邮件文件。
• 不属于任何 matter 的文档。导出会将文档数量与账户总数进行比较，并在 REPORT.md 中说明有多少文档未纳入；若无法验证导出是否完整，则不会声称导出完整。
• Clio 拒绝返回的账户自定义字段。导出会继续进行，但不包含这些字段，并会在 REPORT.md 中说明。如果必需类型无法读取，运行结果会报告为 INCOMPLETE。若出现这种情况，请检查 Clio 开发者应用的权限（见故障排除）。

已知限制：费用按 Clio 活动类型（ExpenseEntry、HardCostEntry、SoftCostEntry）读取，每行均包含其类型。如果 Clio 也在 ExpenseEntry 下列出硬成本和软成本条目，这些行就会在 data/expenses.* 中出现两次。目前尚未发现此情况：我们测试过的账户都没有硬成本或软成本条目。可通过 id 区分各行。

已测试：在 Clio EU 账户上实际运行了导出，包括一个 5 MB 的文档、带重音符号的名称、含双空格和特殊字符的名称、刷新运行（没有重新下载任何文件），以及中断后恢复运行。

所需时间

Clio 在工作时间内允许每个令牌每分钟约发起 50 次请求。默认速率为每秒 0.8 次，即每分钟 48 次，低于该上限。每页 200 条记录算一次请求，每份文档至少还需一次请求；文件夹树和每个事项的文档也都各需一次请求。因此，拥有 100,000 份文档的律师事务所需要的时间远超一天。大型律师事务所应在周五启动导出，并让它在周末继续运行。--dry-run 会将你账号的请求数和所需时间写入 REPORT.md。试运行本身也必须检查每个事项，平均每个事项约需 1.3 次请求；以每秒 0.8 次请求计算，400 个事项大约需要 10 分钟。从 Clio 的存储链接下载文件不计入请求上限。

停止、恢复和再次运行

导出会在每页处理完后保存进度。按 Ctrl-C（或终止进程），然后使用 --resume 运行相同命令，即可从中断处继续，且不会产生重复行。按 Ctrl-C 会以代码 4 退出。只下载了一部分的文件会被丢弃并重新获取；文件下载完成前不会使用最终文件名。

事项列表会在开始时生成一次，恢复时不会重新生成。首次运行后在 Clio 中创建的事项，只有在不使用 --resume 再次运行时才会纳入导出。这种再次运行相当于刷新：它会重新生成数据文件，跳过磁盘上大小和版本相同的文档，若事项已重命名则移动相应文档，且不会删除任何内容。在 Clio 中已删除的文件会保留在磁盘上，并在 REPORT.md 中计为孤立文件。

如果长时间运行期间登录过期，导出会保存进度并以代码 3 退出。请重新运行 auth，然后使用 --resume 重复相同的命令。

使用 --since

日期（例如 2026-03-10）会被解析为该日期的 UTC 00:00:00，再减去一天，因此筛选范围会略宽，以免遗漏记录。带时区偏移的完整 ISO 日期时间（2026-03-10T09:00:00+02:00）则按原值使用。筛选条件会应用于 Clio 支持 updated_since 的记录类型；其他类型会完整导出，并列在 REPORT.md 中。文件夹始终完整导出，因为文档路径需要文件夹树。每个事项的文档都会检查，不仅限于已更改的事项。日历条目会按年份分段获取，从日期所在年份开始（未使用 --since 时从 1990 年开始），因此开始时间早于该年份的条目不会纳入导出。

退出代码

代码	含义
0	已完成且完整
1	已完成但有错误，或报告显示 INCOMPLETE
2	用法错误，或 --resume 被拒绝（选项或账号不同，或保存的索引已更改）
3	未登录，或登录已过期
4	已中断；可使用 --resume 恢复
5	致命错误

隐私与安全

• 导出不会向 Clio 写入任何内容；Clio 登录信息只会发送到 Clio API，不会发送到 Clio 将文档下载请求重定向到的存储链接。
• 日志、进度行、errors.jsonl 和审计条目只包含记录类型、ID、数量和状态代码，不包含名称、文档标题、文件路径或客户端值。导出的审计条目（来源为 export）会写入你主文件夹中的 ~/.clio-mcp/audit.log，不会写入导出文件夹；试运行也会写入审计条目。
• 导出文件夹以明文形式存储机密法律数据。请将其保存在加密磁盘上。 checkpoint/ 文件夹也会存储客户端名称（事项索引和每个事项的文档记录），因此需要同样的保护。
• 内存占用不会随律师事务所的规模增长：一次只处理一页。文件夹树是例外；下载文档期间，文件夹 ID、父文件夹和名称会保留在内存中，每个文件夹约占 100 字节。
• 请在一个新文件夹中运行 --dry-run：如果文件夹中已有导出内容，它会替换该导出的 REPORT.md。

资源

该连接器还会公开两个 MCP 资源：只读内容，兼容的客户端（包括 Claude Desktop）可以在会话开始时自动显示这些内容。

资源 URI	内容
clio://compliance/notice	一段合规提醒，涵盖 ABA Opinion 512、审计日志记录，以及 AI 生成内容须经律师审核的要求
clio://auth/status	实时身份验证状态：是否已连接、你的 Clio 用户 ID，以及令牌到期前的剩余分钟数

---

配置参考

所有设置都通过环境变量传入（stdio 模式下在 Claude Desktop 配置中设置，HTTP 模式下在服务的环境中设置）。所有模式下均只需设置 CLIO_CLIENT_ID 和 CLIO_CLIENT_SECRET；HTTP 模式还需额外设置 MCP_BASE_URL 和 MCP_API_KEY。

变量	必需	默认值	说明
CLIO_CLIENT_ID	是（自带应用）	—	Clio 开发者应用中的客户端 ID。在所列版本中不使用，也不需要。
CLIO_CLIENT_SECRET	是（自带应用）	—	Clio 开发者应用中的客户端密钥。在所列版本中不使用，也不需要。
TOKEN_BROKER_URL	是（仅所列版本）	—	Oktopeak 托管的令牌代理 URL。通过 Clio App Directory 安装时，设置此项而非 CLIO_CLIENT_ID/CLIO_CLIENT_SECRET。请参阅所列版本／一键安装版本。
TRANSPORT	否	http	stdio 或 http。v2.0.0 起默认值为 http；设为 stdio 可使用 v2 之前的行为
MCP_BASE_URL	HTTP 模式	（无）	此服务的公开基础 URL（例如 http://127.0.0.1:3000）。用于 OAuth 重定向
PORT	否	3000	HTTP 监听端口（仅限 HTTP 模式）
MCP_API_KEY	HTTP 模式	（无）	每个客户端都必须在 Authorization 标头中发送的 Bearer 令牌。HTTP 模式下必需，长度至少为 24 个字符；未设置时服务将拒绝启动。使用 openssl rand -hex 32 生成
MCP_ALLOW_UNAUTHENTICATED	否	false	仅用于本地开发。设为 true 后，HTTP 服务可在未设置 MCP_API_KEY 的情况下启动，并会在启动时打印警告。切勿在公网主机上设置此项
ENCRYPTION_KEY	否	自动生成	覆盖 OS 密钥链。仅在没有可用密钥链的 CI／无头安装环境中需要。必须是 64 个字符的十六进制字符串。
CLIO_REDIRECT_PORT	否	5678	OAuth 回调的本地端口（stdio 模式）。如果 5678 端口已被占用，请更改此项
CLIO_REGION	否	us	Clio 数据区域：us、eu、au 或 ca。用于确定默认的 Clio API 和 OAuth 基础 URL。在创建 Clio 账户时设置；必须与律所登录的服务区域一致。其他任何值都会导致启动失败并报错
CLIO_API_BASE	否	<region host>/api/v4	API 基础 URL 的高级覆盖设置。优先级高于 CLIO_REGION
CLIO_AUTH_URL	否	<region host>/oauth/authorize	OAuth 授权端点的高级覆盖设置
CLIO_TOKEN_URL	否	<region host>/oauth/token	OAuth 令牌端点的高级覆盖设置
READ_ONLY	否	false	设为 true、1 或 yes 后，十二个写入工具不会注册，因此 Claude 可以读取 Clio，但无法更改其中的内容。两种传输方式均适用。请参阅只读模式

只读模式

设置 READ_ONLY=true 后，连接器将不注册其 12 个写入工具（create_matter、update_matter、create_custom_field、create_note、create_task、update_task、complete_task、create_calendar_entry、log_time_entry、create_activity、upload_document、create_folder）。这些工具不会出现在 Claude 的工具列表中，服务器也会拒绝对其中任何工具的调用，因此这是服务器端的保障，而非客户端提示词。读取工具、身份验证工具和审计导出仍可正常工作。如果不启用此模式，Claude 与写入操作之间唯一的防护就是 MCP 客户端显示的审批提示；这由客户端负责，与此连接器无关。

对于 Claude Desktop，将其添加到其他变量旁边：

"env": {
  "CLIO_CLIENT_ID": "...",
  "CLIO_CLIENT_SECRET": "...",
  "TRANSPORT": "stdio",
  "READ_ONLY": "true"
}

每个工具还带有 MCP 注释（readOnlyHint、destructiveHint、idempotentHint），因此支持这些注释的客户端可以在你批准之前显示哪些调用会更改数据。

Clio 区域

Clio 会将每家律所的数据托管在四个区域之一。区域在创建 Clio 账户时选定，连接器无法更改；请将 CLIO_REGION 设为与律所登录的服务器相匹配的值（登录后浏览器地址栏中的主机名）。列表之外的任何值都会导致连接器在启动时停止，并报错列出有效值。系统不会静默回退到美国端点。

CLIO_REGION	Clio 服务器	API 基础地址	OAuth 授权 / 令牌
us（默认）	app.clio.com	https://app.clio.com/api/v4	https://app.clio.com/oauth/authorize、https://app.clio.com/oauth/token
eu	eu.app.clio.com	https://eu.app.clio.com/api/v4	https://eu.app.clio.com/oauth/authorize、https://eu.app.clio.com/oauth/token
au	au.app.clio.com	https://au.app.clio.com/api/v4	https://au.app.clio.com/oauth/authorize、https://au.app.clio.com/oauth/token
ca	ca.app.clio.com	https://ca.app.clio.com/api/v4	https://ca.app.clio.com/oauth/authorize、https://ca.app.clio.com/oauth/token

---

审计日志参考

每次工具调用都会以 JSONL 格式记录在 ~/.clio-mcp/audit.log 中（每行一个 JSON 对象）。示例条目：

{"timestamp":"2026-04-23T14:05:00.123Z","session_id":"3f2e9b1c-...","machine_ip":"192.168.1.42","tool":"get_matter","args":{"matter_id":4821},"outcome":"success","clio_user_id":"10023","matter_id":4821}

每个条目包含：

字段	说明
timestamp	调用的 ISO 8601 日期和时间
session_id	每个会话对应的 UUID（在 stdio 进程的整个生命周期内保持不变；每个 HTTP 会话对应一个）
machine_ip	记录调用的主机的 LAN IPv4 地址。仅适用于 stdio 模式；在容器内，该地址没有意义，因此会省略
user_id	托管服务为多人运行连接器时的调用方身份。在 stdio 和单密钥 HTTP 模式下不存在
request_id	主机的请求 ID，用于将条目与对应的请求日志匹配。除非主机设置了该值，否则不存在
tool	Claude 调用的工具
args	Claude 传入的参数，经过允许列表筛选（见下文）。传入但不在列表中的键会显示为 "[redacted]"，这样记录仍会显示发送了什么，同时不包含实际内容
outcome	success、error 或 not_found
error_message	仅当 outcome 为 error 时出现
clio_user_id	当前凭据对应的 Clio 用户
matter_id	仅适用于特定事务的查询
result_count	仅适用于列表 / 导出工具：返回的记录数量

导出条目

export 命令会将自己的条目写入同一个文件，在 tool 字段中将来源标记为 export：每种记录类型在每个阶段各写入一条（试运行对应 count，其余阶段为 fetch、download）。这些条目仅包含记录类型、阶段和计数，并写入主目录下的 ~/.clio-mcp/audit.log，绝不会写入导出文件夹。试运行也会写入条目，并标记为 "dry_run":true。

{"timestamp":"2026-10-19T12:00:00.000Z","session_id":"3f2e9b1c-...","tool":"export","args":{"type":"documents","phase":"download","pages":0,"files":120,"bytes":48211904,"since":"2026-03-09T00:00:00.000Z","dry_run":false},"outcome":"success","clio_user_id":"10023","result_count":120}

允许的键包括 type、phase、pages、files、bytes、since 和 dry_run。绝不会记录事务 ID、名称、文档标题或路径，且有测试确保这一点。

永远不会写入日志的内容

参数采用允许列表记录，而不是拒绝列表。对于每个工具，只会原样记录 ID、限制、日期、页令牌、枚举值和布尔值；传入的任何其他参数都会替换为 "[redacted]"。具体来说，日志永远不会包含：联系人搜索查询（search_contacts.query）、文档搜索内容（list_documents.query）、笔记主题或正文、任务名称或描述、日历摘要、描述或地点、事务描述或客户引用、时间条目或活动备注、文件路径或文件名，或 list_users 的名称筛选条件。完整列表位于 src/utils/auditLog.ts 中的 AUDIT_ARG_ALLOWLIST；如果其中添加了自由文本键，测试就会失败。名称中含有机密信息的键（access_token、client_secret、password、token）在所有位置都会被屏蔽，包括嵌套对象内部。

该日志文件只追加内容，本软件不会轮替或截断它。若要归档旧条目，请使用操作系统的日志轮替工具（Linux/Mac 上的 logrotate）。将连接器作为库嵌入的宿主可以通过 configureAudit({ sink }) 将文件替换为自己的存储；记录格式保持不变。

---

故障排查

Claude 提示 Clio 工具不可用 完全重启 Claude Desktop（退出应用，不要只是关闭窗口）。如果问题仍然存在，请检查配置文件中的路径是否正确，以及该文件夹中是否存在 build/index.js。

身份验证打开了浏览器，但之后没有任何反应 请确认 Clio 开发者应用中的重定向 URI 设置为 http://127.0.0.1:5678/callback。末尾不能有斜杠，也不能使用 localhost；必须是 127.0.0.1。

出现 "ENCRYPTION_KEY must be 64 hex chars" 错误 如果环境中设置了 ENCRYPTION_KEY，但长度不正确，就会出现此错误。请更正或移除该值；移除后，连接器将使用存储在操作系统密钥链中的密钥（或在首次运行时生成一个密钥）。

出现 "Token file exists but decryption failed" 警告 如果加密密钥与用于加密令牌文件的密钥不再匹配，就会出现此警告，例如密钥链条目已删除、你更换了设备，或更改了 ENCRYPTION_KEY。请在 Claude 中运行 logout 工具，然后再次运行 authenticate，以使用当前密钥重新创建令牌文件。

注销不会清除密钥链条目 logout 命令会移除已存储的令牌文件，但不会从操作系统密钥链中移除加密密钥。若要彻底清除凭据（例如，准备转让设备时），还需通过系统的密钥链管理器删除 clio-mcp / encryption-key 条目：macOS 上使用 Keychain Access，Windows 上使用 Windows 凭据管理器，Linux 上使用 secret-tool delete --label clio-mcp。

端口 5678 已被占用 请在 Claude Desktop 配置的 env 块中添加 "CLIO_REDIRECT_PORT": "5679"，并将 Clio 应用的重定向 URI 更新为 http://127.0.0.1:5679/callback。 list_custom_fields 返回 403“用户无权执行此操作” 有些配置会拒绝读取自定义字段，即使连接用户是账户所有者，而且令牌对其他所有操作都有效。发生这种情况时，/custom_fields.json 会返回 403，而展开在事项和联系人的自定义字段值会带有 id，但没有名称、类型或值，且完全不会报错。我们于 2026 年 10 月在一个 EU 账户上复现了此问题，并通过连接一个权限正确的 Clio 开发者应用解决了它：使用新应用时，/custom_fields.json 返回了状态码 200 和字段定义，事项上的字段值也可以读取。同一个应用之前在通讯、分配和银行交易方面也曾遭拒绝，权限变更后这些操作也开始正常响应。因此，首先请在 Clio 开发者门户中检查 Clio 开发者应用的权限（即你使用其客户端 ID 的那个应用），然后重新连接（先运行 logout，再运行 authenticate）。如果权限没有问题，请联系 Clio 管理员检查连接用户对自定义字段的访问权限。如果仍无法解释问题，请提供 Clio 区域和确切响应，提交问题。

自定义字段返回了 id，但 name、type 和 value 为 null 原因相同，只是这次没有报错：当应用无权读取自定义字段时，Clio 会静默丢弃展开的属性。发生这种情况时，响应中会带有 custom_fields_warning。请将这些字段视为未读取，而不是空字段；它们在 Clio 中并非空白。export 命令也会在 REPORT.md 中将相同情况报告为 INCOMPLETE。

自定义字段完全消失，而不是显示为空 这是预期行为，并非错误：clear: true（在 update_matter 的 custom_field_values 中）会删除值记录本身，而不只是清除它的值。对于从未设置过的字段，Clio（以及此连接器）仍会返回一个空占位项，其中包含真实的 id 和 value: null；而被明确清除的字段在设置新值前不会有任何记录，因此此连接器的输出和 Clio 自身的界面都不会显示它。如果你希望字段仍显示为空，请设置一个等同于空值的值，而不是清除它。

选项列表显示 display_value: null 和 label_unresolved: true 连接器无法确定所选选项的名称，因此不会显示任何内容，而不是显示内部选项 id。它会先使用 Clio 随值一起发送的标签，然后尝试读取一次字段定义。两种方式都失败，通常意味着存在上述相同的权限问题。

响应中带有 fields_warning Clio 拒绝了部分字段选择，因此请求在移除可选展开项后重试。该响应是真实的，但不完整；缺失字段在 Clio 中不一定为空。请附上引用的消息进行报告。

---

需要的不只是连接器？

这个开源连接器处理了大多数律所最终希望通过 Claude + Clio 实现的功能中约 20%。它能读取您的数据，但不会围绕这些数据构建工作流。

根据您的需求范围，我们可以通过两种方式提供帮助：

→ 整个律所？律所方案：每月 300 美元。 部署在您自己的云端，每位律师使用自己的账号登录，提供统一的审计日志，每月为您构建一个自动化流程，无需设置费，可随时取消。→ oktopeak.com/firm-plan/

→ 法律 AI 集成：适用于多工作流构建、文档自动化、受理自动化、自定义 AI Agent，以及覆盖您整个技术栈的完整合规架构。 → oktopeak.com/services/legal-ai-integration/

从第一天起就符合 ABA Opinion 512。想要了解这个连接器的精美概览、视频演示和常见问题解答吗？ → oktopeak.com/clio-mcp/

想先聊聊吗？→ 预约 30 分钟的需求沟通电话

---

Oktopeak 的其他连接器

我们也为其他律所管理平台提供同类连接器。每个连接器都在 oktopeak.com 上有自己的概览页面：

• MyCase MCP：面向 MyCase 法律业务管理平台的开源 MCP 连接器。采用相同的架构、审计日志记录和静态加密方式。采用 MIT 许可证。源码：github.com/oktopeak/mycase-mcp。npm：@oktopeak/mycase-mcp
• Filevine MCP：面向 Filevine 律所管理平台的开源 MCP 连接器。支持案件、联系人、备注、文档、任务和 Collection 分区。采用相同的架构、审计日志记录和静态加密方式。采用 MIT 许可证。源码：github.com/oktopeak/filevine-mcp。npm：@oktopeak/filevine-mcp
• Lawmatics MCP：面向 Lawmatics 法律 CRM 和客户受理的开源 MCP 连接器，支持在配置层级设置只读模式。采用 MIT 许可证。源码：github.com/oktopeak/lawmatics-mcp。npm：@oktopeak/lawmatics-mcp
• IntakeQ / PracticeQ MCP：面向 IntakeQ/PracticeQ（医疗保健、行为健康及相关医疗诊所）的 HIPAA 适用型 MCP 连接器。每次读取或写入 PHI 时都会记录审计日志，并提供 BAA + Zero-Data-Retention 指引。采用 MIT 许可证。npm：@oktopeak/intakeq-mcp

---

支持这个项目

这个连接器免费、采用 MIT 许可证，并由 Oktopeak 维护。它会一直免费；我们不接受捐赠。如果它为您节省了时间，以下做法确实能帮上忙：

• 为这个仓库点星。 其他律所确实是通过这个方式找到它的。
• 告诉另一家使用 Clio 的律所。
• 如果我们直接帮到了您，请**留下评价**。
• 需要为您的律所部署、扩展或维护？商业支持；这正是为免费服务提供资金的方式。

我们是谁

Oktopeak：为律师事务所和医疗保健行业提供数字化转型服务。

我们是一支由 7 人组成的内部产品团队，致力于为受监管行业构建 AI 解决方案：AI 集成、工作流自动化，以及客户拥有完整所有权的定制软件。我们维护着五个开源 MCP 连接器：Clio、MyCase、Filevine、Lawmatics 和 IntakeQ，并将它们部署在实际业务中，使用范围受限的凭据、审计日志，以及根据团队实际工作方式打造的工作流。

• 🌐 oktopeak.com
• 📅 预约 30 分钟通话
• ✉️ [email protected]（欢迎提交安全问题报告）
• 💼 LinkedIn

---

将连接器用作库

两个传输方式所用的一切都从 @oktopeak/clio-mcp/lib 导出，因此服务可以在自己的服务器中运行相同的 37 个工具，并使用自己的登录、令牌存储和审计存储。公开的 npm 包和本地安装均保持不变；托管服务正是基于这个接口进行构建。

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import {
  registerAllTools, runWithSessionContext, configureAudit,
  buildClioAuthorizeUrl, exchangeClioCode, refreshClioTokens, fetchClioWhoAmI,
} from "@oktopeak/clio-mcp/lib";

// Once at startup: send audit entries to your store instead of ~/.clio-mcp/audit.log.
configureAudit({ sink: myAuditSink });

// Per request: register the tools you want to expose, then run the MCP request
// inside a session context that knows who the caller is and how to get a Clio token.
const server = new McpServer({ name: "my-host", version: "1.0.0" });
registerAllTools(server, { readOnly: false, auth: "none", exclude: ["upload_document"], complianceNotice: "..." });
await runWithSessionContext(
  {
    sessionId: requestId,
    userId, clioUserId, requestId,
    getAccessToken: () => tokenStore.validAccessToken(userId),   // refresh with refreshClioTokens() as needed
    getTokens: () => tokenStore.get(userId),
    storeTokens: (t) => tokenStore.set(userId, t),
    clearTokens: () => tokenStore.clear(userId),
  },
  () => transport.handleRequest(req, res, req.body)
);

Clio OAuth 函数接受显式凭据和区域（buildClioAuthorizeUrl、exchangeClioCode、refreshClioTokens、fetchClioWhoAmI，以及用于 PKCE 的 generateCodeVerifier / deriveCodeChallenge）；库中的任何内容都不会从环境中读取 CLIO_CLIENT_ID。在 stdio 模式之外，如果没有会话上下文，工具就会拒绝运行，因此宿主绝不会意外回退到共享令牌文件。类型定义随包一同发布（build/lib.d.ts）；导出的接口由 src/__tests__/lib.test.ts 锁定。

贡献

欢迎提交问题和拉取请求。如果你遇到此连接器无法妥善处理的 Clio API 边界情况，请提交问题，并附上场景和请求示例。如果你新增工具，请在 src/tools/index.ts 中登记其名称（TOOL_META，以及在工具会更改 Clio 数据时登记到 WRITE_TOOLS），以确保只读限制和注释覆盖该工具；否则 registry.test.ts 将会失败。

---

许可证

MIT © Oktopeak

完整文本请参阅 LICENSE。