capsulemcp 是一个为 Capsule CRM 构建的 Model Context Protocol（MCP）服务器，主要用途是让 Claude（包括 Claude Desktop、Claude Code，以及通过 Custom Connector 接入的网页 Projects）能够以自然语言访问和操作 Capsule CRM 中的记录。它覆盖联系人、组织、商机、项目、任务和时间线活动等完整记录图谱，并支持结构化筛选、保存搜索、工作流轨道、文件附件、已删除记录审计以及批量获取等能力。
主要能力方面，该服务器提供 92 个工具，覆盖 Capsule 资源图谱，其中只读模式下有 53 个工具。它包含完整的读取覆盖，以及经过确认门控的写入操作；另有 6 个批量写入工具（batch_），用于批量更新工作流。工具支持结构化筛选，通过 filter_ 工具包装 Capsule 的结构化筛选端点，接受由 {field, operator, value} 条件组成的数组，条件之间为 AND 关系。由于 Capsule API 不支持临时排序，对于“最近 X”类问题，建议按日期条件筛选并选取结果中最大的 id（Capsule 的数字 ID 单调递增）。若需要可排序查询，可使用保存的筛选器：先在 Capsule 网页界面创建筛选器（可设置条件、列和 orderBy），然后通过 run_saved_filter 调用其 id，并用 list_saved_filters 发现可用筛选器。此外，还支持工作流轨道（模板和实例）、文件附件（读取和写入）、已删除记录审计，以及每次调用最多 50 条记录的批量获取。
使用方式上，支持两种传输方式：stdio 用于本地安装（Claude Desktop / Code），HTTP+OAuth 用于托管的 Custom Connectors，并提供一个未认证的 GET /health 令牌健康页面用于正常运行时间监控。对于大多数个人用户，安装只需将一段 JSON 片段粘贴到 Claude Desktop 的配置中。快速开始步骤为：首先在 Capsule 中生成 API 令牌（My Preferences → API Authentication Tokens → Generate，为安全起见选择 Read 范围）；然后将配置添加到 claude_desktop_config.json（macOS 路径为 ~/Library/Application Support/Claude/claude_desktop_config.json），配置内容为：{ "mcpServers": { "capsule": { "command": "npx", "args": ["-y", "capsulemcp"], "env": { "CAPSULE_API_TOKEN": "<paste token here>", "CAPSULE_MCP_READONLY": "1" } } } }；最后重启 Claude Desktop，Capsule 工具会出现在工具选择器中。首次启动会从 npm 获取包（几秒钟），后续启动从 npx 缓存即时加载。要固定特定版本，可在 args 中使用 "capsulemcp@2.4.0"；若跟踪 fork 或未发布分支，可使用 GitHub-ref 形式："github:soil-dev/capsulemcp#v2.4.0"。
分页与参数方面，大多数记录列表工具默认 perPage=25；参考数据工具默认 perPage=100，因此小型账户通常一次响应即可容纳。所有分页工具的 perPage 上限为 100，当有更多结果时返回 nextPage 游标。许多 GET 工具接受 embed 参数（例如 tags、fields），每个工具的描述会列举其有效令牌（按资源验证；未知令牌会被拒绝而非静默忽略，面向调用方的 project 令牌在传输时映射到 Capsule 的旧版 kase）。
安全与限制方面，可通过设置 CAPSULE_MCP_READONLY=1 在 MCP 层禁用所有写入/删除工具（create_、update_、complete_task、add_note 或 delete_* 均不会注册）。建议搭配具有 Read 范围的 Capsule 令牌以实现纵深防御——无论环境变量如何，令牌的范围都是硬性上限。每个整记录删除工具，以及 remove_track 和 remove_additional_party，都要求在其参数中提供 confirm: true；否则 schema 会在发出任何 HTTP 请求之前拒绝调用。工具描述会指示 Claude 先读取实体并与用户确认后再调用。这种组合设计——只读范围令牌、只读模式标志、schema 级确认门控——意味着破坏性操作是有意为之，而非意外发生。MCP 工具注解方面，53 个读取工具带有 readOnlyHint: true，8 个破坏性工具带有 destructiveHint: true；尊重这些提示的客户端可以自动批准安全读取，同时仍对写入/破坏性调用进行提示。该项目采用 Apache License 2.0，版权归 Anton Arapov 所有（2026）。
