amazing-marvin-mcp

概述

这是一个用于 Amazing Marvin 的非官方 MCP 服务器，因此像 Claude 这样的助手可以回答“我的收件箱里有什么？”、“这周有什么到期的？”、“我在车里，我能做什么？”，并付诸行动：重命名、重新标记、重新排期、移动、拆分成项目、把研究内容保存到笔记中。

本项目与 Amazing Marvin 没有任何关联，未获得其认可或支持；本项目使用其公开 API。

工作原理

Claude ──MCP (stdio)──▶ amazing-marvin-mcp
                          ├─ local mirror ◀── CouchDB `_changes` (your sync database)
                          │    reads, search and filters run here: no rate-limit cost
                          └─ writes ──▶ Marvin REST API (addTask, doc/update, markDone)
                                        throttled to Marvin's limits (1 request / 3 s)

Marvin 的 REST API 没有“列表”或“搜索”端点，并且每天只有 1440 次请求的配额，因此读取操作来自你的数据库的本地副本，并通过增量式 _changes 轮询保持最新（最多每分钟一次）。写操作则通过 REST API 进行，由服务端处理 Marvin 的冲突解决记账（fieldUpdates）。

助手了解什么

• Marvin 语义，用界面自己的话来说。Inbox = 未归入任何地方；类别和项目可以任意嵌套（Master List）。四个日期彼此区分：Do date（你计划执行的那一天，“已排期”）、Due date（外部硬性截止日期）、End date（自己设定的目标；Planning Ahead 中的计划周/月是更柔性的形式）、Start Throught date（在那之前一直藏在 Backburner 中）。另外还有预计时长（分钟）、重要性（P1–P3 星标）、Eat-the-Frog、Backburner、标签和标签组。

• 你的结构（get_structure）：分类/项目树，包含 id 和未完成项目数、按组划分的标签，以及你启用了哪些 Marvin 策略（按 Strategies 屏幕中的名称）。

• 你的工作流（workflow.md 或 workflow/ 目录中的分节）：详细描述 你 如何使用 Marvin：标签的含义、你如何计划、你的收件箱分诊检查单，以及“short win”的含义。Marvin 非常灵活，因此这些内容能让助手像你那样行事。它会被注入到服务器指令中，并作为 marvin://workflow（也有 marvin://workflow/<section>）资源暴露。

Related MCP server: Amazing Marvin MCP

工具

这里刻意没有提供删除工具：Marvin 的回收站只存在于客户端，因此 API 删除将是无法恢复的。

安装和设置（使用）

1. 安装（需要 uv）：

   uv tool install git+https://github.com/tsvikas/amazing-marvin-mcp.git

2. 凭据。 在 Marvin 中，启用 API 策略（Strategies → API → 设置）。将其值放入 ~/.config/amazing-marvin-mcp/.env（Linux 系统；amazing-marvin-mcp check 会输出你系统上的确切路径）：

   MARVIN_API_TOKEN=...           # create / mark done
   MARVIN_FULL_ACCESS_TOKEN=...   # edit existing items; omit for no edits
   MARVIN_SYNC_SERVER=...         # CouchDB: the read mirror
   MARVIN_SYNC_DATABASE=...
   MARVIN_SYNC_USER=...
   MARVIN_SYNC_PASSWORD=...

   环境变量和工作目录中的 .env 在这里同样有效（并会覆盖用户级文件）。在试用时，请使用第二个临时 Marvin 账号：因为全权访问令牌可能会破坏数据。

3. 检查并首次同步：

   amazing-marvin-mcp check     # verifies tokens, pulls the database, prints counts

4. 描述你的工作流：

   amazing-marvin-mcp init-workflow            # one workflow.md to edit, or
   amazing-marvin-mcp init-workflow --split    # a workflow/ directory: planning, labels, triage, daily…

   其中的所有内容都会进入模型的指令（每个章节也会作为一个 marvin://workflow/<section> 资源），因此请保持简短而具体。

5. 注册到你的 MCP 客户端。

   Claude Code：

   claude mcp add marvin -- amazing-marvin-mcp serve

   Claude Desktop（claude_desktop_config.json）：

   {
     "mcpServers": {
       "marvin": { "command": "amazing-marvin-mcp", "args": ["serve"] }
     }
   }

   两者都会读取用户级 .env，因此客户端配置中不需要包含机密信息。然后直接问：“我的 Marvin 收件箱里有什么？”

其他设置（可由 check 显示）：MARVIN_WORKFLOW_FILE（文件或目录）、MARVIN_CACHE_DIR、MARVIN_MIN_REQUEST_INTERVAL（REST 调用之间的秒数，默认 3）、MARVIN_MIRROR_MAX_AGE（读取操作重新默认的次数，默认 60）。

镜像文件包含你所有任务；它以仅所有者权限写入缓存目录。

开发

git clone https://github.com/tsvikas/amazing-marvin-mcp && cd amazing-marvin-mcp
uv sync && just prepare                     # deps + pre-commit hooks
just test && just lint

从 checkout 目录运行服务器（仓库根目录下的 .env 已被 git 忽略；如果客户端从该目录启动，该文件会被读取，否则使用 -e VAR=value 或用户级文件）：

claude mcp add marvin-dev -- uv run --directory "$PWD" amazing-marvin-mcp serve

tests/test_live.py 默认会将每个工具端到端运行，并重放一个已录制的 cassette（tests/cassettes/），这也相当于一个真实 Marvin 文档的 fixture。要针对 一次性 账号重新录制（它会创建并随后删除一些 [live] 项）：

MARVIN_API_TOKEN=... MARVIN_FULL_ACCESS_TOKEN=... MARVIN_SYNC_SERVER=... \
MARVIN_SYNC_DATABASE=... MARVIN_SYNC_USER=... MARVIN_SYNC_PASSWORD=... \
uv run pytest tests/test_live.py --record-mode=rewrite

有关贡献的设计规则见 CLAUDE.md。

贡献

有兴趣贡献吗？请查看 CONTRIBUTING.md 了解开发设置和指南。