amazing-marvin-complete-mcp

一个用于 Amazing Marvin 的 MCP（Model Context Protocol）服务器，完整覆盖公共 API：34 个工具覆盖全部 ~31 个已记录端点，一个尊重 Marvin 文档限制的全局速率限制器，最小权限令牌路由，以及 MCP 工具注解。工具描述中每一个不明显的非平凡行为声明都已针对实时 API 验证——相关发现记录在下面的 Marvin API 怪癖与发现 中，即使你从不运行此服务器，这些内容也可能有用。

按原样提供。 此项目未积极维护，也不提供支持。Issue 被有意禁用。欢迎 fork——它是 MIT 许可的。

工具（34）

有意不包含：智能列表 / 任务挑选逻辑。Marvin 自己的 Spotlight 负责挑选；服务器为你的助手提供双手，而不是观点。

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

Related MCP server: Super-Productivity-MCP

获取你的 Marvin 令牌

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

• API 令牌（MARVIN_API_TOKEN，必需）——受限访问；足以读取和创建任务。

• 完全访问令牌（MARVIN_FULL_ACCESS_TOKEN，可选但推荐）——所有基于 /doc* 的工具都需要：update_task、set_priority、unmark_done、delete_task、类别创建、时间块、list_habits、提醒、reset_reward_points。

像对待密码一样对待它们；参见 SECURITY.md。

安装与运行

需要 Python 3.12+。

git clone <this repo> && cd amazing-marvin-complete-mcp
python -m venv .venv && .venv/bin/pip install .

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

默认传输是 stdio，因此客户端自行启动服务器：

{
  "mcpServers": {
    "amazing-marvin": {
      "command": "/path/to/.venv/bin/marvin-mcp",
      "env": {
        "MARVIN_API_TOKEN": "…",
        "MARVIN_FULL_ACCESS_TOKEN": "…",
        "MARVIN_TIMEZONE": "Europe/Stockholm"
      }
    }
  }
}

（对于 Claude Code：claude mcp add amazing-marvin -e MARVIN_API_TOKEN=… -- /path/to/.venv/bin/marvin-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。内置的 bearer 检查（MCP_AUTH_TOKEN）保护每个路径，但这只是内部屏障，并非完整的身份验证方案：请在前面放置带 TLS 的反向代理，对于 Claude 自定义连接器，请使用支持 OAuth 2.1 的 MCP 身份验证代理。包含用于 HTTP 模式的 Dockerfile（以非 root 用户运行；将卷挂载到 /data 以在重启后保留每日速率限制计数器）。

配置

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

速率限制

Marvin 的文档限制——1 次写入/秒、1 次读取/3 秒、1440 次调用/天——由所有工具和会话共享的单个进程级队列强制执行，并留有裕量（1.1 秒 / 3.1 秒）。每日计数器在重启后保留（STATE_DIR），并在配置时区的午夜重置。get_rate_limit_status 显示今天的用量。

Marvin API 怪癖与发现

以下所有内容均于 2026-08-19 针对实时 API 验证。这是本仓库中你无需运行即可使用的一半内容。

习惯

• 非原始 GET /habits 不会读取你的习惯文档。它读取的是服务器端跟踪注册表，该注册表是在首次记录时惰性创建的——从未被记录的习惯会完全从响应中缺失，且条目不包含标题（只有 habitId + 历史记录）。使用 ?raw=1（完全访问令牌）列出实际的习惯文档。GET /habit?id=… 返回跟踪记录——有历史记录但没有标题。

• POST /updateHabit 拒绝序列化为浮点数的整数："value": 1.0 → 400 错误请求，"value": 1 → 200。请以整数形式发送整数。

任务与项目

• POST /markDone 仅适用于任务——项目会收到 400 "Can only mark Tasks done with this API"。

• /addTask 在服务器端解析 Marvin 的快速添加快捷语法：~15 变为 15 分钟的 timeEstimate，+YYYY-MM-DD 设置 day（计划——不是截止日期）。两者都会从标题中剥离。但切勿通过 API 使用 #Category：服务器会将字符串按字面存储为 parentId（贪婪匹配到第一个连字符，例如 #MCP-TEST → parentId: "#MCP" 和损坏的标题），而不会解析任何 ID。该任务随后会存在于每个类别和收件箱之外——实际上不可见。（首次由 lucasoeth/marvin-mcp 报告；此处独立复现。）

• 重复任务的生成实例具有确定性的 ID（YYYY-MM-DD_<recurringTaskId>），这就是为什么通过 API 将它们标记为完成/未完成不会产生重复项。实例由 Marvin 客户端生成，因此在应用运行之前，今天的重复任务可能会从 /todayItems 中缺失。

• /doc/update 偶尔会返回瞬时 500；写入是原子的（无部分状态）——只需重试。项目重命名、移动、标签更改等都可以通过它完成。

• /doc/create 不会回显服务器生成的 _id——如果你之后需要引用该文档，请自行提供。

• 通过 /doc/delete 删除是永久性的；Marvin 的回收站是客户端行为。

奖励积分与声望

• 声望（XP/等级，通过 /kudos 读取）和奖励积分（领取/取消领取/花费/重置）是两个独立的系统。/kudos 缺少 nextMultiplier（MarvinAPI issue #5）——它在 /me 中。

• /markDone 不会奖励任务的奖励积分（关于声望请参见 issue #6）——claimRewardPoints 是单独的调用。

• MANUAL 领取（itemId: "MANUAL"）无法撤销：服务器不会为其存储任何条目，因此 /unclaimRewardPoints 返回 404 "No such entry"（无论是否带有 points 字段），而领取负积分会被 400 拒绝。Marvin Web 应用从不使用 MANUAL——它是仅限 API 的功能。唯一的补偿是花费相同金额，但这会夸大已花费统计。

• 如果余额将为负，/spendRewardPoints 会返回 500。

提醒

• Marvin 中的任务提醒是两次写入，只有应用才能保持同步：任务文档上的提醒字段（taskTime、reminderTime、reminderOffset、snooze、autoSnooze）以及通过 /reminder/set 的服务器端条目。只写入一侧（API 让你轻松做到的）会产生应用 UI 不会在任务上显示的条目，或服务器端孤立条目。独立提醒（类型 M）是 API 的安全用法。（风险首先由 Recon2026/marvin-mcp 记录；官方 wiki 自己的警告也证实了这一点。）

时间与计划

• /todayTimeBlocks 省略了块↔类别链接（issue #65）；此服务器从 strategySettings.plannerSmartLists 配置文档中恢复映射。

• 通过 API 停止时间跟踪不会更新任务自身的 times/duration 字段；/tracks 是事实来源。

• 通过 /addEvent 创建的日历事件仅在 Marvin 应用在某个地方运行时才会继续同步（客户端日历同步）。

与现有替代方案的区别

存在几个不错的 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）构建。

许可证

MIT。