🔌 开放接入

青蛙Todo 提供两种外部接入方式：

Remote MCP：适合支持 MCP 的 AI 客户端。授权后可以读取、搜索、创建、更新、完成待办，并按权限设置提醒或执行删除预览。
Quick API：适合快捷指令、Raycast、脚本和自动化平台。它只用于快速创建待办，不能读取或修改已有待办。

如果你只是想把一句话快速收集到青蛙Todo，优先使用 Quick API。如果你希望 AI 帮你管理已有待办，使用 Remote MCP。

使用前准备

请先升级到支持“开放接入”的新版青蛙Todo App。MCP 授权需要使用 App 扫码确认，旧版客户端通常只能识别桌面端登录二维码，不能完成 MCP 授权。

进入青蛙Todo App 的“我的”或“设置”页面，打开“开放接入”，可以看到：

MCP URL
Quick Create URL
Quick Token 管理
已授权的 AI 客户端管理

Remote MCP

MCP URL 通常是：

https://frogtodo.shuge888.com/mcp

实际地址以 App “开放接入”页面展示为准。

适合做什么

Remote MCP 适合让 AI 客户端在你授权后操作青蛙Todo，例如：

搜索和读取待办
读取清单
创建待办
更新标题、备注、日期等安全字段
完成或取消完成待办
设置或清除提醒
预览并确认删除待办

授权流程

在支持 Remote MCP 的 AI 客户端中添加 MCP Server。
填入 App 中展示的 MCP URL。
AI 客户端打开青蛙Todo 授权页。
使用新版青蛙Todo App 扫描授权页二维码。
在 App 中检查客户端名称、权限范围和回调地址。
确认授权。
AI 客户端完成登录后即可调用 MCP 工具。

二维码只用于确认本次授权会话，不包含登录 token、access token 或 authorization code。

Codex 配置示例

在本机 Codex 中添加青蛙Todo MCP：

codex mcp add frogtodo --url https://frogtodo.shuge888.com/mcp

然后登录授权：

codex mcp login frogtodo --scopes todo.read,category.read,todo.create,todo.update,todo.complete,todo.reminder.write,todo.delete,offline_access

不要手动指定固定的 client_id。青蛙Todo 会通过 OAuth 动态注册为客户端分配 client_id。

权限范围

Scope	能力
`todo.read`	搜索和读取待办
`category.read`	读取可见清单
`todo.create`	创建待办
`todo.update`	更新安全字段
`todo.complete`	完成或取消完成待办
`todo.reminder.write`	设置或清除提醒
`todo.delete`	预览并确认删除待办
`offline_access`	允许客户端刷新授权，不需要频繁重新扫码

授权后可以在 App 的“开放接入”页面撤销对应客户端。撤销后，外部客户端不能继续刷新 token 或访问 MCP。

Quick API

Quick API 用于把外部文本快速创建成一条待办。它适合：

iOS 快捷指令
Raycast
Home Assistant
Shell 脚本
只需要“快速收集”的简单 AI 工作流

Quick API 不能读取、更新、完成或删除已有待办。如果需要这些能力，请使用 Remote MCP。

创建 Quick Token

打开青蛙Todo App。
进入“开放接入”页面。
创建 Quick Token。
给 token 设置一个容易识别的名称，例如 Raycast、iOS Shortcut 或 Home Assistant。
创建成功后复制 token 原文。
把 token 保存到调用方的安全存储中，例如系统钥匙串、环境变量、快捷指令变量或自动化平台 secret。

Quick Token 原文只展示一次。不要把 token 写进公开文档、Git 仓库、URL 参数或日志。

请求地址

POST https://frogtodo.shuge888.com/externalAi/createQuickTodo/v1

实际地址以 App “开放接入”页面展示的 Quick Create URL 为准。

鉴权

请求必须携带 Bearer token：

Authorization: Bearer <quick-token>

必要 Headers

Header	必填	说明
`Authorization`	是	`Bearer <quick-token>`
`Content-Type`	是	`application/json`
`Idempotency-Key`	是	幂等 key，用于防止重试时创建重复待办

Body 字段

字段	必填	类型	说明
`title`	`title` 和 `text` 二选一	string	待办标题
`text`	`title` 和 `text` 二选一	string	快速收集文本；没有 `title` 时作为标题
`content`	否	string	待办备注
`categoryIndexId`	否	string	目标清单 ID；为空时进入默认位置
`parentIndexId`	否	string	父待办 ID，必须属于目标清单
`importantLevel`	否	integer	重要程度，范围 `0` 到 `2`
`date`	否	string	日期，格式 `YYYY-MM-DD`
`time`	否	string	时间，格式 `HH:mm`
`timezone`	否	string 或 number	时区，例如 `Asia/Shanghai`、`+08:00`、`8`
`reminderTime`	否	string 或 number	提醒时间，可传 ISO 时间、秒级时间戳或毫秒级时间戳

reminderTime 必须配合有效 date 使用。如果同时有 time，提醒时间不能晚于待办日期时间。

最小示例

curl -X POST "https://frogtodo.shuge888.com/externalAi/createQuickTodo/v1" \
  -H "Authorization: Bearer $FROGTODO_QUICK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "text": "买牛奶"
  }'

成功后会返回新建待办的标识：

{
  "code": 200,
  "msg": "success",
  "data": {
    "todoIndexId": "ext_1782345600000_ab12cd34ef56",
    "serverRev": 12345
  }
}

带日期和时间

curl -X POST "https://frogtodo.shuge888.com/externalAi/createQuickTodo/v1" \
  -H "Authorization: Bearer $FROGTODO_QUICK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: meeting-20260625-0930" \
  -d '{
    "title": "准备产品评审",
    "content": "整理 Remote MCP 和 Quick API 接入说明",
    "date": "2026-06-25",
    "time": "09:30",
    "timezone": "Asia/Shanghai",
    "importantLevel": 1
  }'

带提醒

curl -X POST "https://frogtodo.shuge888.com/externalAi/createQuickTodo/v1" \
  -H "Authorization: Bearer $FROGTODO_QUICK_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: review-reminder-20260625" \
  -d '{
    "title": "产品评审",
    "date": "2026-06-25",
    "time": "10:00",
    "timezone": "Asia/Shanghai",
    "reminderTime": "2026-06-25T09:30:00+08:00"
  }'

幂等规则

Quick API 和 MCP 写操作都使用幂等 key 避免重复写入。

同一个用户、同一个 token、同一个操作、同一个幂等 key：

请求内容一致时，服务端返回第一次创建或写入结果，不重复执行。
请求内容不一致时，服务端拒绝请求。

建议每次明确创建新待办时生成新的幂等 key；网络失败后重试同一次请求时复用同一个幂等 key。

常见问题

Quick Token 能不能访问 MCP？

不能。Quick Token 只允许调用 Quick API 创建待办，不能读取、更新、完成或删除已有待办。

MCP 授权必须使用新版 App 吗？

是。MCP 授权二维码需要新版 App 识别 approvalSessionId 和 scanCode，并在 App 内展示授权确认页。旧版通常只支持桌面端登录二维码。

新版 App 还能扫码登录 PC 客户端吗？

可以。新版 App 会先识别 MCP 授权二维码；如果不是 MCP 授权二维码，会继续兼容原来的 PC 登录二维码。

我怀疑 Quick Token 泄露了怎么办？

立即进入 App 的“开放接入”页面撤销对应 Quick Token，并为外部工具重新创建一个新的 token。

使用前准备​

Remote MCP​

适合做什么​

授权流程​

Codex 配置示例​

权限范围​

Quick API​

创建 Quick Token​

请求地址​

鉴权​

必要 Headers​

Body 字段​

最小示例​

带日期和时间​

带提醒​

幂等规则​

常见问题​

Quick Token 能不能访问 MCP？​

MCP 授权必须使用新版 App 吗？​

新版 App 还能扫码登录 PC 客户端吗？​

我怀疑 Quick Token 泄露了怎么办？​