内容
# 马文
从终端使用 [Amazing Marvin](https://amazingmarvin.com)，让像 Claude 这样的 AI 助手读取和更新您的任务。
您可以做两件事：
**与任务列表对话。** 连接到 Claude，说“今天我应该专注什么？”，“把我还没完成的任务移到明天”，或“把这封邮件里的六件事添加到我的工作项目中”。Claude 读取您的真实 Marvin 任务，并在您的真实账户中进行更改。
**输入代替点击。** `marvin` 显示今天的任务。`marvin capture "call the dentist +tomorrow"` 添加一个任务。无需切换应用，无需等待页面加载。
它是免费、开源的，与您现有的 Amazing Marvin 账户配合使用。
---
## 它是什么样子
```
$ marvin
2026-07-26
今天（3）
- 编写迁移计划 （frog，90分钟） [a4f2...]
- 审查 PR #412 （!!，30分钟） [8c1e...]
- 预订航班 （截止日期 2026-07-28） [3b90...]
2小时30分钟预估
即将到期，无指定日期（1）
- 更新护照 （截止日期 2026-07-29） [d55a...]
```
最后一个部分是它存在的原因。具有截止日期且无指定日期的任务是事情悄悄逾期的方式 —— Marvin 知道它，但它不在任何一天的列表中，所以你直到它过期才看到它。这将任务呈现在你面前，以便你有时间处理。
---
## 设置
两种方式都可以。两种方式都需要 Marvin 的六个相同的值，您只需设置一次。
### 仅需 Claude Desktop？无需终端。
1. 从 [最新版本](https://github.com/lucasoeth/marvin-mcp/releases/latest) 下载 `marvin-<version>.mcpb`。
2. 双击它。Claude Desktop 打开并询问是否安装。
3. 将以下步骤中的六个值粘贴到它显示的表单中。
就这样了。你不需要 Node.js、npm 或其他任何东西 —— Claude Desktop 自带所有需要的东西，服务器所需的一切都在文件中。Desktop 将凭证存储在您的操作系统密钥链中。
跳到 [步骤 2](#2-get-your-amazing-marvin-tokens) 查找六个值的位置，然后跳到 [日常使用](#everyday-use)。
### 还要使用命令行？
那么就是三个命令，大约两分钟。
### 1. 安装它
```bash
npm install -g marvin-mcp
```
如果失败并显示“command not found: npm”，则需要先安装 [Node.js](https://nodejs.org) —— 下载 LTS 版本，安装它，然后再次运行命令。
### 2. 获取 Amazing Marvin 令牌
您需要的所有信息都在一个页面上： [**设置 → API**](https://app.amazingmarvin.com/pre?api)。
在顶部，两个按钮生成令牌：
- **API 令牌**
- **完全访问令牌**
在同一页面的进一步下方，在同步数据库部分，有四个值：
- **同步服务器**，**数据库**，**用户**，**密码**
这些是您的账户密码 —— 不要将它们粘贴到公共聊天或 GitHub 问题中。
### 3. 保存它们
```bash
marvin auth \
--api-token 粘贴_API_TOKEN \
--full-access-token 粘贴_FULL_ACCESS_TOKEN \
--sync-server 粘贴_SERVER \
--sync-database 粘贴_DATABASE \
--sync-user 粘贴_USER \
--sync-password 粘贴_PASSWORD
```
它在保存任何内容之前会检查 Marvin 的令牌，如果粘贴错误，您将立即知道，而不是在三个命令之后。令牌以 `=` 结尾，这是人们手动选择时最常遗漏的字符。
就这样。运行 `marvin`，您应该会看到今天的任务。
<details>
<summary>为什么是六个值而不是两个？</summary>
Marvin 的公共 API 没有搜索端点，根本无法返回已完成的任务，因此如果没有同步数据库，搜索意味着遍历您的整个项目树 —— 大约 22 个请求每个搜索，而每天的额度为 1440 个请求，而且它仍然无法看到您已完成的任务。
Marvin 通过限制帐户而不是返回错误来强制执行此额度，因此失败模式是 *您的* 帐户被标记。这不是您应该交给别人的东西作为默认值。使用同步凭证，搜索是一个查询，大约快 20 倍，并且可以看到您的已完成历史记录。
读取使用同步数据库。每次写入仍通过官方 API 进行，因为这是处理冲突解决的方式，当您也在手机上编辑时。
</details>
您的令牌保存在 `~/.marvin/config.json` 中，只能由您的用户帐户读取。您无需再次输入它们，`marvin` 将在任何文件夹中工作。
---
## 日常使用
```bash
marvin # 今天的任务
marvin capture "call the dentist" # 添加任务
marvin capture "file taxes +tomorrow" # ...适用于明天
marvin complete "dentist" # 完成任务
marvin tasks "invoice" # 搜索所有任务
marvin tasks --parent inbox # 您的收件箱
marvin tasks --unscheduled # 已捕获，但从未分配日期
marvin hierarchy # 您的项目和类别
marvin apply --changes '[...]' # 一批更改，一次完成
```
`marvin complete` 接受标题的一部分，因此您无需查找任何内容。
如果片段匹配多个任务，它将停止并显示选项，而不是猜测。
### 截止日期与日期
Marvin 有两个日期字段，混淆它们是造成混乱的最简单方法。此工具重命名它们，以免混淆：
- **`--scheduled-for`** —— 您计划处理它的日期
- **`--due-by`** —— 实际截止日期
```bash
marvin capture "file taxes" --due-by 2026-09-01 --scheduled-for 2026-08-20
```
计划在 8 月 20 日开始。9 月 1 日截止日期。这是两件不同的事情。
### 更改是立即生效的
没有撤销。写入直接发送到 Marvin，而 Marvin 没有撤销，因此特别是删除是永久的 —— 重新创建任务会赋予它新的 ID。
优先完成或重新安排任务而不是删除它。
优先使用一次 `apply` 而不是一系列单独的写入：它是一个有序集合，按顺序应用，一次往返，而不是针对具有每日请求限额的帐户的十二次往返。
在任何命令后添加 `--json`，如果您想将输出输送到其他东西。
---
## 连接 Claude
这是使它不仅仅是一个键盘快捷键的部分。
**Claude 代码：**
```bash
claude mcp add marvin -- marvin-mcp
```
**Claude Desktop** —— 如果您安装了 `.mcpb`，您已经完成了；在“设置 → 扩展”下。否则，请打开“设置 → 开发者 → 编辑配置”并添加：
```json
{
"mcpServers": {
"marvin": {
"command": "marvin-mcp"
}
}
}
```
重启 Claude。配置文件中没有令牌 —— 它读取您已经在步骤 3 中保存的令牌。
然后直接与它对话：
> *"今天我的任务是什么？有什么需要我处理的吗？"*
>
> *"我病了。把今天的所有任务推到星期四。"*
>
> *"这是我会议的笔记 —— 把行动项提取出来并添加到我的工作项目中，附上截止日期。"*
Claude 可以读取和更改您的任务，因此请像对待可以访问您的日历的助手一样对待它。每个写入的工具都标记为破坏性协议，因此行为良好的 MCP 客户端会向您显示调用并在运行前等待您的批准 —— 该批准是检查，因为之后没有撤销。
<details>
<summary>其他 MCP 客户端和从手机远程访问</summary>
任何 MCP 客户端都可以使用 —— 服务器是一个标准的 stdio MCP 服务器，作为 `marvin-mcp` 运行。
对于远程访问（Poke 或无法运行本地进程的任何其他客户端），有一个 HTTP 服务器：
```bash
API_KEY=some-long-random-string npm run mcp:remote
```
它在没有 `API_KEY` 的情况下拒绝启动，因为它可以访问互联网并且对您的任务具有写入权限。生成一个真正的随机字符串并不要重用密码。
客户端使用 `Authorization: Bearer <API_KEY>` 进行身份验证。`?token=<API_KEY>` 查询参数也适用于托管客户端无法设置标头但更喜欢使用标头的客户端：URL 中的密钥最终出现在访问日志、代理日志和 `Referer` 标头中，您无法在日志发送到其他地方后取消密钥的泄漏。
</details>
---
## 您的数据
值得明确说明，因为这需要您的任务列表令牌：
- 它完全在您自己的机器上运行。我的服务器不参与。
- 它只与两个地方通信，都是 Amazing Marvin 的：他们的 API 用于写入，他们的同步数据库用于读取。除此之外，绝无其他。
- 您的令牌存储在 `~/.marvin/config.json` 中，其权限仅允许您的用户帐户读取。它们永远不会传输到任何其他地方，除了 Amazing Marvin。
- 没有遥测、分析、崩溃报告或电话回家。您的任何信息或任务都不会发送给我。
如果您将其连接到 Claude，那么 Claude 会看到它读取的任务 —— 这就是连接它的目的，但值得明确说明。
---
## 它故意不做的事
Marvin 在一个任务上有大约 70 个字段。此工具公开了 9 个：标题、备注、计划日期、截止日期、时间估计、项目、优先级、frog 和标签。
没有习惯、目标、跟踪器、奖励、时间跟踪、重复任务、子任务、依赖关系、延迟或时间块。那不是疏忽，也不是路线图 —— 小表面是为什么该工具可预测到足以交给 AI。如果您需要 Marvin 的全部功能，请使用 Marvin。这适用于日常循环。
---
## 贡献
欢迎提交错误报告和拉取请求。
```bash
npm install
npm test
npm run typecheck
```
添加功能意味着在 `src/core/ops/` 中添加一个文件。CLI 命令和 MCP 工具都是从中生成的，因此两个界面不会出现偏差。`AGENTS.md` 有架构和 Marvin API 怪癖列表，这些都是通过实践发现的 —— 在更改任何与 API 交互的内容之前请阅读它。
MIT 许可。 不隶属于 Amazing Marvin LLC。
