Amazing Marvin (complete)

amazing-marvin-complete-mcp

一个适用于 Amazing Marvin 的 MCP（Model Context Protocol）服务，完整覆盖公开 API：涵盖 Marvin API 端点页面中的 38 个端点，共提供 50 个工具（页面于 2026-10-12 阅读；以下所述的两个端点除外）；包含遵循 Marvin 文档所述限制的全局速率限制器、遵循最小权限原则的令牌路由，以及 MCP 工具注释。截至 1.1.0 版本，Marvin 官方数据模型（Tasks 和 Categories/Projects）中的每个可写字段都已由工具支持，或明确记录为不支持，详见 docs/field-reconciliation.md。工具描述中所有不明显的行为说明都已通过实时 API 验证——相关发现记录在下文的 Marvin API quirks & findings中，即使你不运行此服务，这些信息也可能对你有所帮助。

维护状态： 欢迎并感谢提交错误报告——它们有助于让这个项目持续为大家服务。请注意，这是一个在时间允许时维护的个人项目：我们会查看错误报告，但回复时间不定，功能请求则不太可能得到处理。若需要安装帮助，请将此 README 粘贴给你的 AI 助手，它能比我更快地指导你完成设置和故障排除。本项目按原样提供，不作任何保证——采用 MIT 许可证，欢迎自由分叉。

工具（50）

分组	工具
核心	test_connection、create_task、mark_done、mark_project_done、unmark_done、update_task、set_priority、delete_task
读取	get_today_items、get_due_items、get_done_items、get_children、get_categories
重复任务	create_recurring_task、update_recurring_task
笔记本	get_notebooks、get_notebook、search_notebooks、create_notebook、update_notebook、delete_notebook、create_notebook_page、update_notebook_page、delete_notebook_page
结构	create_category_or_project、update_category_or_project、convert_category_or_project（实验性）
习惯	list_habits、get_habit、record_habit
时间块	get_today_time_blocks、create_time_block（实验性）
时间跟踪	get_tracked_item、start_tracking、stop_tracking、get_time_tracks
Kudos/奖励	get_kudos、claim_reward_points、unclaim_reward_points、spend_reward_points、reset_reward_points
其他	get_labels、get_goals、get_reminders、set_reminder、delete_reminder、create_event（实验性）、get_account_info、get_rate_limit_status、list_capabilities

功能概览

list_capabilities（不会调用 Marvin API）会返回与下表相同的映射，按工具列出可以和不可以执行的操作，以及仅能在应用中执行的操作。在认定某件事无法通过 MCP 完成之前，请先调用它。服务器还会在 initialize 时发送一段简短的 instructions 文本（Claude Code 会显示，claude.ai 客户端不会显示）。每个工具描述的第一行都是一个不超过 75 个字符的完整句子，用来说明其功能——客户端在目录中只显示这一行；测试 tests/test_discoverability.py 会对其进行检查。同一测试还会确保每个描述和 instructions 文本都不超过 2,048 个字符——自 v2.1.280 起，Claude Code 会静默截断更长的文本。

区域	可通过 MCP 执行	无法通过 MCP 执行（需在应用中完成）
任务	创建/更新/完成/删除；优先级和 frog 1–4；大小；子任务；在应用表单中设置一天中的时间和自定义提醒；日期、截止日期、标签、预估、备注、分区、计划周/月、复查日期、待办池、orbit、稍后提醒、时间块；完成一个包含未完成任务的项目（分两步）；按应用所示读取今天的任务、到期任务和已完成任务，并进行筛选	创建时设置 startDate（之后可通过 update_task 更新）；修复已存在的重复任务；重新打开已完成的项目
重复任务	创建全部十一种类型（自定义类型只能使用 RRULE 字符串）；更改规则/时间范围/位置/属性；清理不再符合规则的重复项（列出、确认）	重复任务的提醒/frog；重复项目；用文字描述自定义规则
笔记本	列出、读取、搜索、创建、重命名；分区；页面：创建/编辑/移动/删除；分两步删除笔记本	撤销（API 不提供垃圾箱）
结构	层级结构、子项；创建/更新/转换类别和项目；为两者添加标签；颜色、图标、备注；读取标签和目标	创建/编辑标签、目标、智能列表、策略
习惯	列出、跟踪记录、记录/撤销；调用 mark_done 时记录习惯任务，调用 unmark_done 时撤销记录	创建/编辑习惯
时间	查看今天的时间块及映射；创建时间块；时间跟踪的开始/停止/历史记录	设置时间块的智能时间块映射
奖励	kudos；奖励积分的发放/撤销/消费/重置	撤销 MANUAL 发放；读取应用中的奖励
提醒	任务的自定义提醒（列出 + 服务器条目）、独立提醒、删除；通过 update_task 设置一天中的时间	—
日历	创建事件（实验性）	读取/编辑事件
账户	测试、账户信息、调用额度、功能概览	—

刻意未纳入：智能列表/任务挑选逻辑（由 Marvin 自己的 Spotlight 挑选；服务器为你的助手提供操作能力，而非主观意见），以及两个有文档说明但未提供工具的端点： /reminder/deleteAll（刻意未纳入）——它会在一次调用中清除所有提醒，而 delete_reminder 已能满足针对性清理需求；以及 /downloadAttachment（不支持附件）。

每个工具都带有 MCP 工具注解 （readOnlyHint、destructiveHint、idempotentHint、openWorldHint），以便功能完善的客户端能以应有的谨慎程度对待 delete_task 和 reset_reward_points。

获取 Marvin 令牌

两个令牌都位于 Amazing Marvin 的 Settings → API （app.amazingmarvin.com/pre?api）：

• API Token（MARVIN_API_TOKEN，使用时必需）——访问权限有限； 足以读取和创建任务。即使没有此令牌，服务也会启动 （因此 MCP 客户端和目录可以列出工具），但在设置令牌之前， 每次工具调用都会返回明确的错误。
• Full Access Token（MARVIN_FULL_ACCESS_TOKEN，可选但 建议设置）——所有基于 /doc* 的工具都需要此令牌：update_task、 set_priority、unmark_done、delete_task、创建类别、时间块、 list_habits、提醒、reset_reward_points。

请像对待密码一样妥善保管它们；参见 SECURITY.md。

安装和运行

需要 Python 3.12+。

从 PyPI 安装（推荐）：安装 uv 后 无需进行任何设置——按下文所示，将 MCP 客户端指向 uvx amazing-marvin-complete-mcp 即可。

从源代码安装：

git clone <this repo> && cd amazing-marvin-complete-mcp
python -m venv .venv && .venv/bin/pip install .
# then use /path/to/.venv/bin/marvin-mcp as the command below

本地（stdio）——Claude Desktop、Claude Code 和任何 MCP 客户端

默认传输方式为 stdio，因此客户端会自行启动服务：

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "uvx",
      "args": ["amazing-marvin-complete-mcp"],
      "env": {
        "MARVIN_API_TOKEN": "…",
        "MARVIN_FULL_ACCESS_TOKEN": "…",
        "MARVIN_TIMEZONE": "Europe/Stockholm"
      }
    }
  }
}

（对于 Claude Code：claude mcp add amazing-marvin -e MARVIN_API_TOKEN=… -- uvx amazing-marvin-complete-mcp。）

远程（Streamable HTTP）

MCP_TRANSPORT=http PORT=8787 MCP_AUTH_TOKEN_FILE=/path/to/token \
MARVIN_API_TOKEN_FILE=/path/to/api-token .venv/bin/marvin-mcp

MCP 端点为 /mcp。HTTP 模式采用默认拒绝策略：如果未设置 MCP_AUTH_TOKEN（或 MCP_AUTH_TOKEN_FILE），服务将拒绝启动， 并在错误消息中提供说明；只有在确实要在 localhost 上运行开放实例时， 才设置 MCP_ALLOW_UNAUTHENTICATED=true。内置的 bearer 检查会保护所有路径， 但它只是内部防护措施，并非完整的身份验证方案： 请在前面配置带 TLS 的反向代理；对于 Claude 自定义连接器，请使用支持 OAuth 2.1 的 MCP 身份验证代理。项目附带了用于 HTTP 模式的 Dockerfile （以非 root 用户运行；在 /data 上挂载卷，以便在重启后保留每日 速率限制计数器）。

配置

所有设置都通过环境变量配置——完整注释列表请参见 .env.example。 重点：每个密钥都支持 *_FILE 变体（推荐）；MARVIN_TIMEZONE 应与 你的 Marvin 账户所在时区一致（默认为系统时区，大多数容器中的系统时区为 UTC）。

速率限制

Marvin 文档规定的限制——请求间隔不得短于 3 秒、批量创建每秒最多一次、 每天最多 1440 次调用——由一个供所有工具和会话共享的进程级队列执行， 并留有余量：只有创建类调用（/addTask、/addProject、/addEvent、 /doc/create）使用 1.1 秒间隔；其他所有调用（读取、更新、/markDone、 删除）均等待 3.1 秒。间隔时长由即将执行的调用类型决定。收到 429 后， 所有调用都会暂停 60 秒（或遵循 Retry-After）。每日计数器和上次调用时间 会在重启后保留（STATE_DIR），计数器会在配置时区的午夜归零。 get_rate_limit_status 会显示今日用量，以及距离上次调用已经过去的时间。 多步骤工具（链式调用）在遇到 500 或 429 后会重试出错步骤一次；若仍然 失败，则会报告已完成的步骤。

Marvin API 的特性与发现

以下所有内容均已通过实时 API 验证（2026-08-19 至 2026-10-12）。无需运行项目即可利用仓库中这一部分内容。

习惯

• 非 raw 的 GET /habits 不会读取你的习惯文档。它读取的是 服务端跟踪注册表，该注册表会在首次记录时延迟创建——从未记录过的 习惯完全不会出现在响应中，而且条目不包含标题（只有 habitId 和 历史记录）。使用 ?raw=1（Full Access Token）可列出实际的习惯文档。 GET /habit?id=… 返回跟踪记录——包含历史记录，但没有标题。
• POST /updateHabit 会拒绝序列化为浮点数的整数： "value": 1.0 → 400 Bad request，"value": 1 → 200。整数请以整数形式发送。 任务与项目
• POST /markDone 仅适用于任务——项目会返回 400 "Can only mark Tasks done with this API"。
• 默认情况下，/addTask 会在服务端解析 Marvin 的部分快速添加快捷语法： ~15 会变成 15 分钟的 timeEstimate，+YYYY-MM-DD 会设置 day（排期——不是截止日期），而 *p1..*p3 会设置优先级。 这三种语法都会从标题中移除。请注意，优先级映射与存储字段的方向相反： *p1（最高）→ isStarred: 3， *p2 → 2，*p3（最低）→ isStarred: 1。其他魔法词（*urgent、 *fire、*heavy、*weight、*love、*lowfocus、*physical）和 $ 词（例如非重复任务中的 $MONTH）不会被解析—— 它们会原样存储在标题中，不会设置任何字段；只有在应用的快速添加中才有效。 但 # 快捷语法非常危险：标题中的任何 #word（包括类似 #123 的 工单引用）都会原样存储为 parentId（贪婪匹配到第一个连字符为止，例如 #MCP-TEST → parentId: "#MCP"，并导致标题损坏），且不会解析任何 ID—— 即使同一请求中明确提供了 parentId，也会被覆盖。 该任务随后会同时脱离所有类别和收件箱—— 实际上不可见。（最初由 lucasoeth/marvin-mcp 报告；此处进行了独立复现并补充了更多情况。） 本服务不受此问题影响： create_task 会发送未公开的 X-Auto-Complete: false 请求头（在 MarvinAPI#50 中加入），该请求头会禁用所有快捷语法解析——标题会原样存储，而 time_estimate_minutes 参数可替代 ~15 快捷语法 （timeEstimate 的单位是毫秒：15 分钟 = 900000）。
• /addProject 存在相同的 #word 损坏问题，但会忽略 X-Auto-Complete 请求头（实时测试：即使设置了该请求头，标题仍会被截断， parentId 仍会被损坏）。因此，本服务会在本地阻止项目标题中出现 # （在客户端层、发起任何 API 调用之前），并返回说明性错误。类别标题是安全的—— 它们通过 /doc/create 创建，该接口不会解析任何内容。
• /addEvent 不受影响（实时测试于 2026-08-25）：含有 #word 的事件标题会原样存储，无论是否设置请求头——快速添加解析错误 只存在于 /addTask 和 /addProject 中。
• 重复任务生成的实例具有确定性 ID（YYYY-MM-DD_<recurringTaskId>）， 因此通过 API 将它们标记为完成或未完成不会产生重复项。这些实例由 Marvin 客户端生成，因此在应用运行之前，今天的重复任务可能不会出现在 /todayItems 中。
• /doc/update 偶尔会暂时返回 500；写入是原子的（不会产生部分状态）—— 只需重试。项目重命名、移动、标签更改等操作都可通过它完成。
• 对于不存在的文档（已删除或从未创建；实时测试于 2026-08-29）， /doc/update 会返回 500 而不是 404——因此，持续出现的 500 表示“ID 错误或已失效”，而不是服务器错误或文档损坏。
• /addTask 和 /addProject 会忽略 startDate/endDate （实时测试于 2026-08-29）——只能之后通过 /doc/update（更新工具）设置。 /addProject 也会忽略 color/icon（通过 update_category_or_project 设置），而 /addTask 会静默丢弃 noAutoOrbit（实时测试于 2026-09-13）——创建任务后通过 update_task 设置。
• Marvin 完全支持任务上的时钟时间（Time/taskTime）；启用自动创建提醒后， 设置 Time 会自动在相同时间创建提醒（实时数据，2026-09-02）。在 1.8.0 之前，本 MCP 会将其留给应用处理；从 1.8.0 起，工具会按应用自身的格式写入 （字段和服务器条目一并写入——见下文的提醒与一天中的时间）。
• 项目使用字符串字段 priority（"high"/"mid"/"low"）设置优先级， 而任务使用 isStarred（实时测试于 2026-08-29）——因此 set_priority 仅适用于任务。映射（根据应用代码核实于 2026-08-30）： high = 最重要（红色），mid = 非常重要（橙色），low = 重要 （黄色，一星级）。应用的第四级 低优先级（向下箭头）在任务中存储为 isStarred: -1（魔法词 *low/*p0）；项目没有此级别——将低优先级 任务转换为项目时，应用会清除优先级。set_priority/create_task 接受 -1。
• 可以读取已完成的任务，方法是使用未公开的端点 GET /doneItems?date=YYYY-MM-DD（OpenAPI 规范和 wiki 中均未列出；实时测试于 2026-08-30，可能随时消失）。它按任务的 day 筛选，而不是按 doneAt； 过去的 day 在任务完成后仍会保留，无论是在应用中还是通过 /markDone 完成（对于未排期和日期在未来的任务，应用才会将 day 设置为今天）。 因此，get_done_items 会获取指定日期及之前 7 天的数据，并按 doneAt 筛选；响应会说明其覆盖范围（covers_from、days_fetched），完整结果会 缓存 30 分钟；遇到 429 时，工具会返回已获取的内容，并标记为 incomplete/days_missing。也可以通过 /doc?id= 读取单个已完成任务。 /todayItems、/dueItems 和 /children 会排除已完成项； /doneTasks 和 /completedItems 会返回 404。
• 即使请求间隔为 3 秒，Marvin 也会返回 429：当短时间内超过每日平均请求量 （每天 1440 次，即“每分钟 1 次”）时，就会触发限流；该短时间窗口未公开。 2026-08-30 观察到，一小时内约 100 次调用后便触发限流。收到 429 后，限流器会 暂停所有调用 60 秒（或遵循 Retry-After），并记录响应头（仅记录允许名单中的 名称）。
• 服务器不会验证任何写入（实时测试于 2026-08-29）：无效日期、负数或超范围 数值、类型错误的值、空标题、失效的 parentId/labelIds 和未知字段都会通过 /doc/update 原样存储（通过 /addTask 也几乎全部如此）。因此，工具会在客户端 验证日期（严格采用 YYYY-MM-DD 格式，年份为 2000-2100）、标题和数值范围； 不会验证引用（说明中已注明孤立项风险）。
• 对从未存在或已经删除的 ID，/doc/delete 均会响应 200——具有幂等性，不会返回 404（与 /doc/update 不同）。而 /markDone 对缺失的 ID 会正确返回 404， 对已完成的任务会返回 400——三个端点对“对象不存在”的处理各不相同 （实时测试于 2026-08-29）。
• 读取端点（/todayItems、/dueItems）是纯日期筛选：backburner、startDate 和孤立状态（失效的 parentId）不会影响结果——孤立项也不会显示在 unassigned 下（实时测试于 2026-08-29）。启用日期滚动时， /todayItems?date=X 会返回所有 day <= X 的未完成项，而不只是 X 当天的项 （实时测试于 2026-09-11）。/markDone 会停止正在运行的时间跟踪，现在还会 写入 task.times（实时测试于 2026-09-02；2026-08-29 时还不会写入—— 服务器行为已更改）。直接调用 /track STOP 仍不会写入 times；在这种情况下， 唯一记录是 /tracks。
• wiki 中的数据类型未包含 orbit/noAutoOrbit，但实时数据中存在这些字段 （布尔值，已于 2026-08-29 核实）——它们作为明确标记为未公开的直通参数， 在更新工具中开放。
• 项目↔类别转换会就地进行：_id、createdAt 和子项都会保留 （2026-08-29 已通过应用字段测试和 API 核实）。应用有两种行为不同的转换路径 （2026-08-30/31 已核实）：Edit Settings 按钮会永久清除 day/dueDate/priority/isFrogged，但会留下 firstScheduled （这是 Marvin 跟踪器中的一个 bug）；右键/悬停路径则可以无损往返——但该按钮 默认不在菜单中（通过右键菜单中的齿轮图标 → 添加操作来添加）。 从 1.5.0 起，convert_category_or_project 默认采用无损转换；传入 clear_project_fields=True 可创建干净的类别（之前的值会在 removed_project_fields 中返回）。没有官方转换端点——该工具会直接设置 type，这是未公开的服务器行为，并标记为实验性功能。
• /doc/create 不会返回服务器生成的 _id——如果之后需要引用该文档，请自行提供 ID。
• 通过 /doc/delete 删除是永久性的；Marvin 的回收站是客户端功能。
• API 写入后应用中的视图（实时测试于 2026-09-12，PWA 和 Windows 桌面应用 1.70.0 同时打开）：创建、字段更改以及在类别/收件箱之间移动 都会立即显示，无需任何操作。删除则完全不会反映出来——等待或切换视图都 无济于事。Planning Ahead 开启时清除 plannedWeek/plannedMonth 的情况 （2026-08-29），以及策略切换也是如此（该方法的规则自 2026-08-29 起适用）。 操作规则：(1) 通过读取服务器数据进行确认（对父项调用 get_children——任务应 已不在其中）；(2) 如果应用仍显示该行，那只是应用中的视图，不是错误——在应用中 操作该行之前重新加载客户端：网页应用/PWA 中按 F5，重启桌面应用 （它没有刷新功能）。之所以要在操作该行之前重新加载，是因为如果服务器上的文档 已被删除，却仍在应用中编辑该行，客户端的冲突解决机制可能会重新创建该文档 （2026-09-12 仅观察到一次，发生在两个客户端中的一个；具体是哪一个没有记录； 已向上游报告）。这是 Marvin 客户端视图的问题——不要与 get_done_items 自身 30 分钟的缓存混淆，后者的方向相反（应用 → MCP）。 奖励积分与 Kudos
• Kudos（XP/等级，通过 /kudos 读取）和奖励积分 （领取/取消领取/消费/重置）是两个独立系统。/kudos 缺少 nextMultiplier（MarvinAPI issue #5）——该字段在 /me 中。
• /markDone 不会发放任务的奖励积分（关于 Kudos，请参阅 issue #6）—— claimRewardPoints 是单独的调用。
• MANUAL 领取（itemId: "MANUAL"）无法撤销：服务器不会存储此类记录，因此 /unclaimRewardPoints 会返回 404 "No such entry"（无论是否带有 points 字段），而领取负积分会被拒绝并返回 400。Marvin Web 应用从不使用 MANUAL——它是仅供 API 使用的功能。唯一的补偿方式是消费相同数量的积分，这会导致已消费统计虚增。
• 如果余额会因此变成负数，/spendRewardPoints 会返回 500。
• 应用中可购买的奖励是独立的 db="Rewards" 文档，公共 API 完全无法访问这些文档（2026-08-29 实测：/rewards 及其所有变体均返回 404，没有奖励资料文档，且 /doc 需要一个无法获知的 ID）。Task 字段 isReward 与应用的奖励流程相互独立，通过 API 设置该字段不会产生任何 UI 效果。

提醒

• Marvin 中的任务提醒需要进行两次写入，只有应用会确保两者同步：任务文档中的提醒字段（taskTime、reminderTime、 reminderOffset、snooze、autoSnooze）以及通过 /reminder/set 添加的服务器端记录。只写入其中一侧（API 能轻松做到的操作）会导致应用 UI 不显示任务提醒，或产生服务器端孤立记录。独立提醒（类型 M）是使用原始 API 的安全方式；自 1.8.0 起，这些工具会像应用一样写入两侧。（风险最早由 Recon2026/marvin-mcp 记录； 官方 wiki 自身的警告也证实了这一点。）

时间与规划

• /todayTimeBlocks 不包含时间块与类别的关联（issue #65）；此服务器会从 strategySettings.plannerSmartLists 资料文档中恢复该映射。
• 通过直接调用 /track STOP 停止时间跟踪，不会更新任务自身的 times/duration 字段；/tracks 才是事实来源。 在时间跟踪仍处于活动状态时调用 /markDone，会同时写入 times（2026-09-02 实测）和 duration（2026-09-13 已验证；启用 Time Tracking 时，应用会在 Completed Today 下显示已跟踪时间）。
• 通过 /addEvent 创建的日历事件，只有在某处运行着 Marvin 应用时才会继续同步（客户端日历同步）。 API 设置字段的 UI 行为（已于应用中验证，2026-08-29）
• 切换策略后，需要重启应用，字段才会显示——不重启的话，新启用的策略不会显示任何内容，看起来像是出错了。
• backburner 仅对未安排的项目有效：在 UI 中，安排日期（day）优先于该标记。请同时设置 day: "unassigned" 和 backburner: true。
• startDate 会在开始日期之前隐藏 backburner 项目（这是「开始日期」策略的实际机制）——不会隐藏已安排的任务。
• 图标名称带有库前缀（lucide-Rocket、huge-happy）或使用 emoji。只有在 Master List → Configure View → “Show Custom Icon On” 中包含项目时，项目才会显示自己的图标——“Categories & Projects”（已于 2026-08-31 验证）或 “Just Projects”（已于 2026-09-18 验证）；此前“项目永远不会显示自己的图标”的说法是我们自己的测试错误。
• 项目自身的 timeEstimate 优先；如果没有设置，项目会显示其子项预估时间的总和（依据 Marvin 支持团队对我们报告的回复——我们此前关于“不会汇总”的结论，源于设计不当的测试：项目及其子项都设置了预估时间）。
• 已推迟的任务（itemSnoozeTime）在类别视图中也会隐藏——wiki 所说的“除主列表外，其他地方都会隐藏”在此处并不成立。
• timeBlockSection 会将任务关联到 Today 中某个时间块的分区——但前提是已启用 Time Block Sections 策略、日视图按时间块分组（Group by → Group by time block section；每台设备单独设置，不会同步），且任务安排在该时间块所在的日期。设置了此字段的未安排任务完全不会显示在 Today 中。时间块本身不需要标签／类别映射；该映射（Smart Time Block）是另一条独立途径。已于 2026-09-17 在应用中验证（1.70.0.0，PWA + 桌面端）；此前“已存储但未渲染”的结论是我们自己的测试错误（未设置分组），现已撤回；对 Marvin 支持团队的更正尚待回复。自 1.7.0 起，create_time_block 会返回 time_block_id（由客户端设置，因为 /doc/create 不会返回服务器 ID），可直接用作 time_block_section。
• reviewDate 会显示在 Review 视图中；要让它显示在日视图横幅中，还需要使用 “Review Alert” 工作流片段。
• 如果启用了自动 Orbit，新安排的任务会被加入 Orbit，除非设置了 noAutoOrbit。
• 写入类别的仅适用于项目的字段（day、dueDate、priority、isFrogged）会被服务器静默接受（已于 2026-09-11 在线测试）。update_category_or_project 仍会进行类型检查并阻止这些字段，原因是结构性的：类别不会被完成，因此这些字段属于项目和任务。labelIds 则不同——类别与项目使用同一字段存储标签，API 设置的标签会被存储并显示（已于 2026-09-11 在线测试并在应用中验证），因此自 1.6.0 起，类别允许使用 label_ids。

重复任务和出现项（已于 2026-10-09 至 2026-10-11 在线测试）

• 出现项的 ID 格式为 YYYY-MM-DD_<recurringTaskId>；勾选完成一个 完成后重复 任务所创建的出现项会获得随机 ID，且只有第一个会通过 API 写入（echo: true、echoId: null）。调用 /markDone 后，下一个出现项会安排在当天加上 echoDays 的日期。
• 未提供 createAhead 或将其设为 null，表示使用账户默认值。应用仅能将 RRULE 字符串形式的 custom 规则正确显示，因此这些工具仅接受 RRULE（不接受诸如“每隔一个星期五”这类文字规则）。
• 按照应用中 Just this one 的方式删除某个出现项，会将其 ISO 日期添加到重复任务的 deletedDates 中。
• 启用 Only on weekdays 时，若某月的某一天落在周末，则会移至周五。
• 出现项会继承标签、优先级、大小、备注、分区、子任务（ID 为 <day>_<subid>）以及 dueIn → dueDate。 笔记本
• 创建笔记本后 5 秒和 12 秒时，GET /notebook?parentId= 均返回 404“Notebook not found”，而此时 ?id= 返回 200（原因未知）。随后，使用 parent_id 调用 get_notebook 会返回错误，提示应使用 notebook_id。
• 项目的 notePageId 由服务端根据 rank 最低的页面计算得出；写入项目的 note 会写入该页面。
• 在应用中删除项目（连同其笔记）后，服务端上的笔记本和页面仍会保留，仍会通过 /notebooks 和 /notebook?parentId= 列出。get_notebooks 会将此类笔记本标记为 parent_missing（若项目已完成，还会标记为 parent_done）。

提醒和时刻

• 时刻由 taskTime（“HH:MM”）和任务上的 reminderTime（秒）及相关字段构成，服务端还会有一个类型为 T 的条目，其 reminderId 为任务 ID。自有提醒则由任务上的 reminders 列表和各一个类型为 M 的条目构成。
• 在应用中完成任务会从服务端移除 T 和 M 条目；撤销完成状态不会恢复 T，但 M 仍会通知。删除带有提醒的任务前，也要删除其服务端条目，否则打开的客户端会继续提醒。

习惯

• 使用 undo 调用 /updateHabit 时，总是会移除最新的历史条目；如果同时发送 time，还会追加 [time, 0]。切勿在使用 undo 时发送 time。
• 低于数值目标的记录不会写入习惯任务（habitRepAt 保持为 null）。

完成项目及其他文档行为

• 应用完成项目时，会在一次带时间戳的写入中写入 done、doneAt = workedOnAt、day（若未设置则为今天）和 doneDate = day，且在子项尚未完成时会拒绝操作。 mark_project_done 的行为与此一致。
• /categories 不会列出已完成的项目。
• /markDone 不会设置 workedOnAt，也不会为 fieldUpdates 添加时间戳；对于没有 day 的任务，它会将 day 设为今天，同样不添加时间戳。
• 对已删除文档调用 GET /doc 会返回 200，并响应 {"error":"not_found","reason":"deleted"}；对其调用 /doc/update 会返回 500。
• /addTask 会丢弃 taskSize（XS–XL = 1–5）；之后需通过 /doc/update 写入。

速率限制

• 入门指南写道：“请求频率不得高于每 3 秒 1 次”。限流器对创建操作（/addTask、/addProject、/addEvent、/doc/create）间隔 1.1 秒，对其他所有操作间隔 3.1 秒，并根据即将发出的调用类型进行限流。

与现有替代方案的差异

已经有几个不错的 Amazing Marvin MCP 服务；这个服务是在研究它们之后从头构建的（没有共享代码），目标有所不同——完整覆盖公开 API，而不是精选子集：

• bgheneti/Amazing-Marvin-MCP — 成熟的 Python 服务；覆盖面广但不完整，且没有全局速率限制。
• Recon2026/marvin-mcp — 范围较小（19 个工具），研究格外细致；考虑到双写风险，选择让提醒仅支持读取。此服务则提供提醒写入，并附有明确警告。
• lucasoeth/marvin-mcp — 理念不同：提供少量整合的工作流工具（brief/capture/…），而不是镜像 API；此外还会直接读取 CouchDB 来搜索和获取已完成的任务（公开 API 完全无法做到这一点）。如果你想要有主张的工作流或搜索功能，请使用他们的服务；如果你想要完整、原始的 API 访问，并了解其中的风险，请使用这个服务。
• LucaDeLeo/amazing-marvin-mcp — Limited-API 子集。

致谢与来源

本项目没有复制以下任何项目的代码——这是全新构建的——但它们对本项目产生了实质性影响：

• amazingmarvin/MarvinAPI （另见 wiki）——本服务所依据的官方 API 文档、OpenAPI 规范、数据类型和问题跟踪器。
• bgheneti/Amazing-Marvin-MCP ——架构灵感、初期差距分析期间的端点参考，以及 MIT 许可先例。
• Recon2026/marvin-mcp ——关于 双写完整性风险的提醒，以及对重复任务实例的前期研究；两者都已在此验证并记录。
• lucasoeth/marvin-mcp ——#Category 快捷语法漏洞（已在此复现），以及 Marvin 的同步数据库实际上是可用于读取的 CouchDB 这一发现。
• LucaDeLeo/amazing-marvin-mcp ——指出 /addTask 会在服务端解析快捷语法（部分证实、部分驳斥——参见 #Category 的发现），以及 MCP 工具注解的构想。

使用 Claude Code 构建（Claude Fable 5、Fable 5.1 和 Opus 5.5）。

许可证

MIT。