AI 智能体（MCP）

所有套餐均可使用

MCP 在所有套餐上都能使用。Free 和 Basic 可以只读访问全部 10 个读取工具（Free 每天限 100 次请求）。Pro 和 Ultra 获得完整的读写权限（27 个工具），如果你愿意，也可以切换到只读模式。

MCP（Model Context Protocol）可以让你把 ChatGPT、Claude 等 AI 助手、编程助手和自动化工具直接连接到你的 TellDone 数据。连接后，你的助手可以读取你的笔记、任务、事件、报告、标签和更改历史。在 Pro 及以上套餐中，它还可以创建、更新、删除和恢复条目。共有 27 个工具：10 个用于读取（所有套餐），17 个用于写入（Pro 及以上）。

在 iPhone 上，设置 > 集成 > AI 智能体（MCP） 会打开 MCP 设置屏幕，你的访问令牌默认处于隐藏状态：

iPhone 上设置中的 AI 智能体，令牌已隐藏

网页版如下：

网页版设置中的 AI 智能体，访问令牌已隐藏

两种连接方式

连接 AI 客户端有两种方式：

使用 TellDone 登录（OAuth）（推荐）- 你用 TellDone 账户登录，并批准 App 请求的权限。ChatGPT 和 Claude 使用这种方式，无需复制令牌。
Bearer 令牌 - 从设置中复制你的访问令牌，粘贴到客户端的配置里。对脚本、命令行工具，以及没有内置 OAuth 流程的客户端来说最简单。

客户端	推荐方式
ChatGPT（chatgpt.com 或 ChatGPT 桌面应用，不支持手机应用）	OAuth - 用 MCP URL 添加自定义 MCP 服务器，然后登录
Claude（网站、Desktop、iPhone App）/ Cowork	OAuth - 用 MCP URL 添加自定义连接器，然后登录
Claude Code（CLI）	目前使用 Bearer 令牌 - 添加带有你的令牌的 `Authorization` 头
脚本或你自己的代码	Bearer 令牌 - 最容易自动化
只支持从已列出的连接器目录中选择的客户端	用 MCP URL 把 TellDone 添加为自定义连接器，或使用 Bearer 令牌。TellDone 目前还没有进入任何连接器目录

套餐要求

套餐	MCP
Free	只读（10 个读取工具），每天 100 次请求
Basic	只读（10 个读取工具），没有每日限制
Pro	读写（27 个工具）- 可切换到只读模式
Ultra	读写（27 个工具）- 可切换到只读模式

Free 每天 100 次请求的限制只统计工具调用。连接、登录和列出工具都不计入。这里的一天按你账户中保存的时区计算，在午夜重置。达到限制时，你的助手会收到一条相应的提示消息。写入工具在 Free 和 Basic 上会被拒绝。使用访问令牌时，它们会回复说该连接是只读的，创建和编辑需要 Pro 及以上套餐。使用登录（OAuth）时，大多数会回复“Insufficient scope”，因为 Free 和 Basic 的连接永远不会获得写入权限。

应用内屏幕

打开 设置 > 集成，在 AI 智能体部分轻点 AI 智能体（MCP）。屏幕上会显示“让 ChatGPT、Claude 和其他 AI 助手使用你在 TellDone 中的笔记、任务和事件。”以及你的套餐：

Free：“你的套餐：只读权限，每天 100 次请求。写入功能需升级到 Pro。”
Basic：“你的套餐：只读权限”
Pro 和 Ultra：“你的套餐：读写权限”

MCP 关闭时，轻点启用将其打开。

启用后，屏幕会显示：

访问模式（Pro 和 Ultra）- 随时选择只读或读写。
连接助手 - ChatGPT、Claude 和其他助手的步骤。你在助手中登录 TellDone，所以不需要令牌。
已连接的应用 - 你已连接的助手，每个都带有断开按钮。在第一次连接之前，这里一直是空的。
面向开发者（默认折叠）- 访问令牌字段（隐藏，带显示 / 隐藏和复制）、重新生成令牌，以及一个 Claude Code / Cursor / 其他切换，附带现成的文本和各自的复制按钮。Claude Code 给你 claude mcp add 命令，Cursor 给你 .cursor/mcp.json 的 JSON，其他列出服务器地址、OAuth 登录选项和 Authorization: Bearer 请求头。令牌隐藏时，代码片段中显示的是 YOUR_TOKEN。轻点显示后，它们就包含你真实的令牌。

网页版有同样的控件，只是布局不同，没有折叠的开发者部分：带复制按钮的 OAuth 地址、你的令牌控件、带断开的已连接的应用，以及有六个客户端可选的手动配置 Bearer 令牌（Claude Code、Cursor、Windsurf、Codex、OpenClaw 和 cURL）。在网页版上，即使令牌字段是隐藏的，代码片段里也始终包含你真实的令牌，所以请把它们当作令牌本身一样对待。

文档 - 指向本页面的链接。
停用 - 关闭 MCP。你需要确认“所有已连接 AI 工具的访问权限将被撤销。”你的令牌会被删除，所有连接都会停止。如果你再次启用 MCP，会得到新的令牌，通过登录（OAuth）连接的 App 无需重新登录即可再次使用。要彻底移除某个 App，请在已连接的应用下轻点断开。

提示

请妥善保管你的访问令牌。任何拥有令牌的人都可以访问你的 TellDone 数据。如果你怀疑令牌已经泄露，请轻点重新生成令牌。

如何启用

你可以在任一平台上配置 MCP：

iPhone： 设置 > 集成 > AI 智能体（MCP）
网页： app.telldone.app > 设置 > 集成 > AI 智能体（MCP）

步骤：

轻点启用。
在 Pro 和 Ultra 上，选择你的访问模式（只读或读写）。Free 和 Basic 是只读的。
要连接 ChatGPT 或 Claude，请在连接助手下轻点它，并按步骤操作（见下文）。不需要令牌。
对于 iPhone 上的编程客户端，打开面向开发者，轻点显示，选择 Claude Code、Cursor 或其他，然后轻点代码片段下方的复制。如果你在轻点显示之前复制，代码片段里会用 YOUR_TOKEN 代替你的令牌。在网页版上，请在手动配置 Bearer 令牌下选择你的客户端并复制代码片段；它已经包含你的令牌。
把代码片段粘贴到你的客户端或它的配置文件中。

通过 OAuth 连接

OAuth 是 ChatGPT、Claude 和 Cowork 的推荐方式 - 你用 TellDone 账户登录，而不是复制令牌。

OAuth 使用的 MCP URL： https://api.telldone.app/mcp/user

同一个服务器也可以通过 https://api.telldone.app/mcp/user/mcp 访问，两个地址都接受 Bearer 令牌。OAuth 登录请使用第一个。

ChatGPT

你可以在 chatgpt.com 或 ChatGPT 桌面应用中添加自定义 MCP 服务器。ChatGPT 手机应用无法添加自定义连接器，TellDone App 里是这样说的：“ChatGPT 应用只能从其目录中添加连接器。”在 TellDone 中轻点将步骤发送到我的电脑，就能在电脑上收到说明。在那里添加后，TellDone 在 ChatGPT 手机应用中也可以使用。

App 中的步骤：

在电脑上打开 chatgpt.com/plugins，点击 Add，然后选择 Add custom MCP server。
将其命名为 TellDone，粘贴下方地址（https://api.telldone.app/mcp/user）并选择 OAuth。
确认并安装后，登录 TellDone 并允许访问。

如果菜单名称有变化，请参阅 OpenAI 的自定义 MCP 服务器指南。

Claude（网站、Desktop、iPhone App）/ Cowork

App 中的步骤：

在 Claude 中，打开 Customize → Connectors 并轻点 Add custom connector。
粘贴下方地址（https://api.telldone.app/mcp/user）。
登录 TellDone 并允许访问。

登录时，TellDone 的授权页面会显示是哪个 App 在请求访问，以及它想要的具体权限。用你的 TellDone 邮箱和密码登录，然后点击允许访问；或者轻点通过 Apple 登录或使用 Google 登录，它们会在同一步完成授权。Claude 会自动连接 - 无需复制令牌。

如果菜单名称有变化，请参阅 Anthropic 的添加自定义连接器指南。

通过 Bearer 令牌连接

对于 Claude Code、Cursor 和其他没有内置 OAuth 登录的客户端，把你的访问令牌直接粘贴到客户端的配置中。在下面所有示例中，请把 YOUR_TOKEN 替换为你设置中的令牌。

Claude Code（Bearer 令牌）

claude mcp add --transport http telldone \
  https://api.telldone.app/mcp/user/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

你不必自己输入这些：在 设置 > 集成 > AI 智能体（MCP）> 面向开发者 中，轻点显示，选择 Claude Code，然后轻点复制。复制出来的命令已经包含你的令牌。

Cursor

添加到 .cursor/mcp.json（或者轻点显示后，从 面向开发者 > Cursor 复制）：

{
  "mcpServers": {
    "telldone": {
      "url": "https://api.telldone.app/mcp/user/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

其他客户端

其他 MCP 客户端的设置：

Codex

添加到 codex.json：

{
  "mcpServers": {
    "telldone": {
      "type": "http",
      "url": "https://api.telldone.app/mcp/user/mcp",
      "headers": { "Authorization": "Bearer YOUR_TOKEN" }
    }
  }
}

OpenClaw

Settings > MCP Servers > Add:

Name: TellDone
URL: https://api.telldone.app/mcp/user/mcp
Auth: Bearer YOUR_TOKEN

其他 MCP 客户端

任何支持基于 HTTP 的 MCP 的工具都可以连接。使用端点 https://api.telldone.app/mcp/user/mcp，并带上 Bearer YOUR_TOKEN 授权请求头。

备用认证请求头

如果你的客户端或代理占用了 Authorization 请求头（例如某些 Smithery 风格的网关），请改用 X-MCP-Token: YOUR_TOKEN 发送令牌。两种请求头都可以；如果同时存在，以 Authorization 为准。

测试你的连接

你可以用一个简单的 cURL 命令来验证令牌是否有效：

curl -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

成功的响应会列出所有可用的工具。

权限（scope）

OAuth 连接是有范围限制的 - 登录时，你会看到客户端请求的具体权限，并需要明确批准。

Scope	允许 App...
`notes:read`	读取你的笔记并打开笔记的完整详情（search 工具还需要 `tasks:read` 和 `events:read`）
`notes:write`	创建、编辑和删除笔记（process_note 还需要 `tasks:write` 和 `events:write`）
`tasks:read` / `tasks:write`	读取 / 创建、编辑、完成和删除任务
`events:read` / `events:write`	读取 / 创建、编辑和删除事件
`reports:read`	读取你的每日、每周、每月和年度报告
`tags:read` / `tags:write`	列出你的标签 / 创建、置顶、删除和恢复标签
`profile:read`	读取你的账户信息和订阅
`offline_access`	保持登录状态（签发刷新令牌，这样你不必每次会话都重新登录）

Scope 限制了一个连接能做什么：只有 notes:read 的连接无法调用写入工具。你的套餐在此之上设定了第二层限制。

Bearer 令牌连接不会逐个设置 scope - 它们只受你的套餐的读写模式管理。

你可以做什么

读取工具（10 个）- 所有套餐

工具	作用
get_notes	列出笔记，可按标签、日期范围、文本搜索筛选
get_note	查看单条笔记及其子任务、事件和完整转写文本
get_notes_full	一次调用获取多条笔记，并内嵌任务和事件
get_tasks	列出任务，可按状态（待办、已完成、全部）、标签或日期筛选
get_events	列出日历事件，可按日期范围筛选
get_reports	读取你的每日、每周、每月和年度报告（完整 markdown）
get_tags	查看你的所有标签，按使用次数排序
get_profile	查看你的账户信息，以及你有多少笔记、任务和事件
search	在笔记、任务和事件中搜索（文本搜索 + 笔记的语义搜索）
get_change_log	查看笔记、任务或事件的编辑历史，以及每次编辑是否已被撤销

提示

search 工具支持笔记的语义搜索 - 它按含义而不仅是关键词来查找结果。例如，搜索“预算会议”，即使笔记里没有“预算”这个词，也能找到关于财务讨论的笔记。

写入工具（17 个）- Pro 和 Ultra

工具	作用
process_note	完整的 AI 流程 - 发送文本或音频，得到一条带有任务、事件和标签的笔记
create_note	添加一条纯文本笔记（不做 AI 分析）
create_task	添加任务，可设置优先级、截止日期、提醒和标签
create_event	添加日历事件，可设置日期、时间、地点、提醒、参与者和重复规则
update_note	更改笔记的标题、摘要、类型、标签、优先级或状态
update_task	更改任务的标题、描述、优先级、截止日期、提醒、标签或状态
complete_task	把任务标记为已完成
update_event	更改事件的详情、时间、地点、提醒、参与者、重复规则、标签或状态
delete_note	删除一条笔记。它的任务和事件会保留
delete_task	删除一个任务
delete_event	删除一个事件
undo_change_log_entry	撤销一次被记录的编辑 - 无论是 AI 做的还是你自己做的 - 把字段恢复为之前的值
restore_entity	找回已删除或已归档的笔记或任务，或已删除或已取消的事件
create_tag	创建新标签，或把自动建议的标签变成永久标签
set_tag_pinned	置顶或取消置顶标签，使其排在最前面
delete_tag	移除标签（可以用 restore_tag 恢复）
restore_tag	找回已删除的标签

所有写入和删除操作会立即显示在你已连接的设备上（手机、网页版）。

工具参考

get_notes

列出笔记，可选筛选。日期筛选使用 recorded_at（你录制语音笔记的时间），没有该字段的笔记则使用 created_at。

参数	类型	默认值	说明
`limit`	int	20	返回的笔记数量（最多 50）
`offset`	int	0	跳过这么多条笔记（用于分页，最大 10000）
`tags`	string	-	按标签筛选，以逗号分隔（匹配任意一个）
`search`	string	-	在标题和摘要中进行文本搜索
`date_from`	string	-	开始日期，YYYY-MM-DD（包含）
`date_to`	string	-	结束日期，YYYY-MM-DD（不包含）
`standalone_only`	bool	false	为 true 时，隐藏跟进笔记（附属于某条父笔记、任务或事件的笔记），只返回独立笔记

返回：笔记列表，包含 id、title、summary、type、tags、priority、status、recorded_at、created_at。

get_note

获取单条笔记，包括完整转写文本以及所有关联的任务和事件。

参数	类型	说明
`note_id`	string	笔记的 UUID

返回：笔记，包含 title、summary、transcript、type、tags、priority、status、metadata、created_at，以及 tasks[] 和 events[] 数组。

还会返回 transcript_speakers（带说话人标签的转写片段，适用于有多位说话人的会议，否则为 null）、speaker_count（除非录音已按说话人拆分，否则为 null），以及 parent_note_id/parent_task_id/parent_event_id（当这条笔记是对另一个条目的跟进编辑时设置）。每个 tasks[]/events[] 条目还包含 reminders_at/recurrence_rule（任务）或 reminder_minutes/attendees/recurrence_rule（事件）。

get_notes_full

一次调用获取多条笔记及其任务和事件。筛选条件与 get_notes 相同，只是没有 search，并且每条笔记都内嵌了 tasks[] 和 events[]。

参数	类型	默认值	说明
`limit`	int	10	笔记数量（最多 20）
`offset`	int	0	跳过这么多条笔记
`tags`	string	-	按标签筛选
`date_from`	string	-	开始日期，YYYY-MM-DD
`date_to`	string	-	结束日期，YYYY-MM-DD
`standalone_only`	bool	false	为 true 时，隐藏跟进笔记（附属于某条父笔记、任务或事件的笔记），只返回独立笔记

get_tasks

列出任务，支持筛选。

参数	类型	默认值	说明
`status`	string	"todo"	筛选：`todo`、`done` 或 `all`
`limit`	int	30	任务数量（最多 100）
`offset`	int	0	跳过这么多个任务
`tags`	string	-	按标签筛选，以逗号分隔
`date_from`	string	-	开始日期，YYYY-MM-DD（按截止日期筛选；没有截止日期的任务会被排除）
`date_to`	string	-	结束日期，YYYY-MM-DD（按截止日期筛选；没有截止日期的任务会被排除）

返回：任务列表，包含 id、title、description、status、priority、tags、deadline、reminder_at、reminders_at、completed_at、completed_by、source、created_at。reminder_at 是 reminders_at 第一项的镜像，用于向后兼容 - 要查看一个任务的所有提醒，请使用 reminders_at。

get_events

列出日历事件，支持按日期范围筛选。

参数	类型	默认值	说明
`limit`	int	30	事件数量（最多 100）
`offset`	int	0	跳过这么多个事件
`date_from`	string	-	第一天，YYYY-MM-DD，按你自己的时区（包含）。与该范围重叠的事件也会包含在内，所以跨多天的事件会显示在它覆盖的每一天
`date_to`	string	-	最后一天，YYYY-MM-DD，按你自己的时区（包含）

返回：事件列表，包含 id、title、description、status、start_at、end_at、location、is_all_day、tags、note_id、reminder_minutes、attendees、recurrence_rule、created_at。

get_reports

获取你的 AI 生成的报告，包含完整的 markdown 内容。

参数	类型	默认值	说明
`report_type`	string	"daily"	类型：`daily`、`weekly`、`monthly` 或 `yearly`
`limit`	int	5	报告数量（最多 10）

返回：报告列表，包含 id、type、period_start、period_end、content_md、created_at。

备注

每月报告很长（经常远超 1,000 个词）。如果你的 AI 工具上下文窗口很紧，请使用 limit=1。

get_tags

获取你的所有标签，置顶的排在前面，然后按使用次数排序。

没有参数。最多返回 100 个标签，每个包含 tag、usage_count、is_pinned、is_manual。

get_profile

获取你的账户信息，以及你有多少笔记、任务和事件。

没有参数。返回 email、display_name、locale、transcription_locale、timezone、subscription、mcp_mode、created_at 和 stats（笔记 / 任务 / 事件的数量）。

search

一次在笔记、任务和事件中搜索。对于笔记，同时支持文本搜索和语义搜索（用 AI 嵌入按含义查找结果）。

参数	类型	默认值	说明
`query`	string	必填	搜索文本（最多 500 个字符）
`limit`	int	20	每种类型的最大结果数（最多 20）
`semantic`	bool	true	为笔记启用语义搜索

返回按类型分组的结果：notes[]、tasks[]、events[]。每个结果包含 id、type、title、detail、created_at。

设置 semantic=false 可以进行更快的纯文本搜索。

get_change_log

查看笔记、任务或事件的编辑历史 - 每一次 AI 做的跟进编辑和你自己做的每一次手动编辑，最新的在前。

参数	类型	默认值	说明
`entity`	string	必填	`notes`、`tasks` 或 `events`
`entity_id`	string	必填	条目的 UUID
`include_manual`	bool	false	同时包含你自己的手动编辑，而不仅是 AI 做的编辑

返回：更改条目的列表，包含 id（用作撤销时的 entry_id）、field_name、old_value、new_value、source（follow_up、smart_context、correction_sync（TellDone 在整条笔记中同步的名称修正），或 manual）、origin_note_id、edited_at，以及 reverted_at（撤销后设置）。

process_note（Pro 和 Ultra）

完整的 AI 流程 - 效果和在 App 中录音相同。发送文本或音频，TellDone 会转写、用 AI 分析，并创建一条结构化的笔记，其中包含提取出的任务、事件、标签和嵌入向量。

这个工具是异步的：它会立即返回一个 audio_id，并在后台处理。结果会通过实时同步到达你已连接的设备，你也可以用 get_notes() 轮询。

参数	类型	说明
`text`	string	必填。要分析的文本。如果它不为空，就会用作转写文本，你发送的任何音频都不会被转写；发送 `""` 则会转写音频。未发送音频时的限制：Pro 20,000 / Ultra 50,000 个字符
`audio_base64`	string	Base64 编码的音频文件。整个请求限制为 10 MB，所以音频本身大约 7 MB。仅当 `text` 为空时才会转写
`audio_format`	string	`m4a`、`ogg`、`wav`、`mp3`、`aac` 或 `webm`（默认：m4a）
`parent_task_id`	string	这是对哪个任务的跟进，填该任务的 UUID
`parent_note_id`	string	这是对哪条笔记的跟进，填该笔记的 UUID
`parent_event_id`	string	这是对哪个事件的跟进，填该事件的 UUID

请始终发送 text。要让 TellDone 转写音频，请发送 audio_base64，并把 text 设为空字符串（""）。如果 text 不为空，TellDone 会把它用作转写文本，不会转写音频。三个父 ID 最多只能设置一个。

返回：{"audio_id": "...", "status": "processing", "mode": "text-only"}，如果提供了音频则为 "mode": "audio+stt"。

备注

process_note 受你的套餐配额限制（每天上传次数、每月笔记数、文本最大长度）。get_profile 只显示你有多少笔记、任务和事件，不显示你的限额。请在 App 的 设置 > 用量 中查看你的用量。

create_note（Pro 和 Ultra）

立即创建一条纯文本笔记。不会触发 AI 分析 - 不会提取任务或事件。如果你想让 TellDone 为你找出任务和事件，请使用 process_note。

参数	类型	限制	说明
`title`	string	200 个字符	必填
`summary`	string	1000 个字符	可选。简短的摘要（1-3 句）。会用于你的报告，所以请保持简短
`transcript`	string	取决于套餐	可选。显示在笔记详情中的长篇正文。不会包含在报告中。限制：Pro 20,000 / Ultra 50,000 个字符
`type`	string	-	可选。`task`、`idea`、`info`（默认）、`status`、`meeting`、`event` 或 `reflection`
`tags`	string	20 个标签	以逗号分隔，可选
`suppress_external_sync`	boolean	-	可选，默认 false。导入或批量添加条目时设为 true：这样该条目就不会发送到你已连接的应用或自动化

create_task（Pro 和 Ultra）

创建新任务。任务也会在你已连接的 Todoist、Notion 或 Microsoft To Do 中创建，你的自动化会收到 task.created。传入 suppress_external_sync: true 时不会发生这些。

参数	类型	限制	说明
`title`	string	200 个字符	必填
`description`	string	2000 个字符	可选
`priority`	string	-	`low`、`medium`（默认）或 `high`
`deadline`	string	-	YYYY-MM-DD，可选
`reminder_at`	string	-	ISO 8601 日期时间（例如 `2026-04-15T09:00:00Z`），可选
`tags`	string	20 个标签	以逗号分隔，可选
`note_id`	string	-	用于把任务关联到父笔记的 UUID，可选
`suppress_external_sync`	boolean	-	可选，默认 false。导入或批量添加条目时设为 true：这样该条目就不会发送到你已连接的应用或自动化

create_event（Pro 和 Ultra）

创建日历事件。事件也会在你已连接的 Notion 中创建，你的自动化会收到 calendar_event.created。传入 suppress_external_sync: true 时不会发生这些。

参数	类型	限制	说明
`title`	string	200 个字符	必填
`start_at`	string	-	ISO 8601 日期时间，必填
`end_at`	string	-	ISO 8601 日期时间（默认：开始时间 + 1 小时；全天事件为一天）
`description`	string	2000 个字符	可选
`location`	string	200 个字符	可选
`is_all_day`	bool	-	默认：false
`tags`	string	20 个标签	以逗号分隔，可选
`reminder_minutes`	string	-	事件前多少分钟提醒，以逗号分隔（例如 `15,60`），可选
`attendees`	string	-	以逗号分隔的姓名或邮箱，可选
`recurrence_rule`	string	-	RRULE 字符串（例如 `FREQ=WEEKLY;BYDAY=MO,WE,FR`），可选。比每小时更频繁的规则，或永远不会发生的规则，会被拒绝
`note_id`	string	-	用于把事件关联到父笔记的 UUID，可选
`suppress_external_sync`	boolean	-	可选，默认 false。导入或批量添加条目时设为 true：这样该条目就不会发送到你已连接的应用或自动化

update_note（Pro 和 Ultra）

更新现有笔记的一个或多个字段。只有你提供的字段会被更改。效果和在 App 中编辑笔记完全相同：它的标题、摘要、标签和类型会同步到对应的 Notion 页面，你的自动化会收到 note.updated，这次编辑也会出现在更改记录中，可以撤销。对转写文本的更改同样会保存并发送到 Notion，但不会出现在更改记录中。

参数	类型	说明
`note_id`	string	必填，笔记的 UUID
`title`	string	新标题（最多 200 个字符）
`summary`	string	新摘要（最多 1000 个字符，传入一个空格 `" "` 可清除）
`transcript`	string	新的转写文本（取决于套餐的限制，传入一个空格 `" "` 可清除）
`type`	string	`task`、`idea`、`info`、`status`、`meeting`、`event` 或 `reflection`
`tags`	string	以逗号分隔的标签（替换所有现有标签，最多 20 个）
`priority`	string	`low`、`medium` 或 `high`
`status`	string	`active` 或 `archived`

警告

对于由语音流程创建的笔记，transcript 是语音转文字的原始输出。覆盖它会替换你的原话。想保留原话，请在转写文本后面追加内容，而不是替换。

update_task（Pro 和 Ultra）

更新现有任务的一个或多个字段。只有你提供的字段会被更改。效果和在 App 中编辑任务完全相同：更改会同步到它在 Todoist、Notion 和 Microsoft To Do 中的副本，你的自动化会收到 task.updated，这次编辑也会出现在任务的更改记录中，可以撤销。把 status 设为已完成，效果和 complete_task 一样。截止日期可以是日期，也可以是完整的日期和时间（只取其中的日期）。每个标签最多 50 个字符。

参数	类型	说明
`task_id`	string	必填，任务的 UUID
`title`	string	新标题
`description`	string	新描述（传入一个空格 `" "` 可清除）
`priority`	string	`low`、`medium` 或 `high`
`deadline`	string	YYYY-MM-DD。这个工具无法清除截止日期；请在 App 中清除
`status`	string	`todo` 或 `done`
`tags`	string	以逗号分隔的标签（替换所有现有标签，最多 20 个）
`reminder_at`	string	ISO 8601 日期时间（传入一个空格可清除）

把 status 设为 done 还会记录任务是何时、以何种方式完成的。

complete_task（Pro 和 Ultra）

把任务标记为已完成的快捷方式。

参数	类型	说明
`task_id`	string	必填，任务的 UUID

如果任务不存在或已经完成，会返回错误。

update_event（Pro 和 Ultra）

更新现有事件的一个或多个字段。只有你提供的字段会被更改。效果和在 App 中编辑事件完全相同：更改会同步到对应的 Notion 页面，你的自动化会收到 calendar_event.updated，这次编辑也会出现在更改记录中，可以撤销。

参数	类型	说明
`event_id`	string	必填，事件的 UUID
`title`	string	新标题
`description`	string	新描述（传入一个空格可清除）
`start_at`	string	新的开始时间（ISO 8601）
`end_at`	string	新的结束时间（ISO 8601）
`location`	string	新地点（传入一个空格可清除）
`status`	string	`confirmed`、`tentative` 或 `cancelled`
`tags`	string	以逗号分隔的标签（替换所有现有标签，最多 20 个）
`is_all_day`	string	`"true"` 或 `"false"`
`reminder_minutes`	string	事件前多少分钟提醒，以逗号分隔（例如 `15,60`，传入一个空格可清除）
`attendees`	string	以逗号分隔的姓名或邮箱（传入一个空格可清除）
`recurrence_rule`	string	RRULE 字符串（传入一个空格可清除）

delete_note（Pro 和 Ultra）

删除一条笔记。只会删除笔记本身：它的任务和事件会保留。效果和在 App 中删除完全相同：你的自动化会收到 note.deleted。Notion 中的笔记副本不会被移除（App 也不会移除它）。

参数	类型	说明
`note_id`	string	必填，笔记的 UUID

delete_task（Pro 和 Ultra）

删除一个任务。效果和在 App 中删除完全相同：它在 Todoist、Notion 和 Microsoft To Do 中的副本也会被删除，你的自动化会收到 task.deleted。可以用 restore_entity 找回。

参数	类型	说明
`task_id`	string	必填，任务的 UUID

delete_event（Pro 和 Ultra）

删除一个事件。效果和在 App 中删除完全相同：你的自动化会收到 calendar_event.deleted。该事件在 Notion 中的页面不会被移除（App 也不会移除它）。

参数	类型	说明
`event_id`	string	必填，事件的 UUID

undo_change_log_entry（Pro 和 Ultra）

撤销一次被记录的编辑 - 把字段恢复为该次编辑之前的值，无论这次编辑是 AI 做的（来自跟进录音），还是你直接做的。

参数	类型	说明
`entity`	string	必填，`notes`、`tasks` 或 `events`
`entity_id`	string	必填，条目的 UUID
`entry_id`	string	必填，来自 `get_change_log` 的更改条目的 `id`

返回：{"entry_id", "entity_type", "entity_id", "field_name", "restored_value", "reverted_at"}。对同一个条目撤销两次会返回错误 - 它已经被撤销了。

restore_entity（Pro 和 Ultra）

找回已删除或已归档的笔记或任务，或已删除或已取消的事件。

参数	类型	说明
`entity`	string	必填，`notes`、`tasks` 或 `events`
`entity_id`	string	必填，条目的 UUID

返回：以 JSON 表示的已恢复条目。

create_tag（Pro 和 Ultra）

创建新标签，或把现有的自动建议标签变成永久标签。

参数	类型	说明
`tag`	string	必填，1-50 个字符（以小写存储）
`category`	string	可选

set_tag_pinned（Pro 和 Ultra）

置顶或取消置顶标签，使其排在标签列表的最前面。

参数	类型	说明
`tag`	string	必填
`pinned`	bool	必填

包含 / 字符的标签无法置顶。

delete_tag（Pro 和 Ultra）

移除标签。可以用 restore_tag 找回。

参数	类型	说明
`tag`	string	必填

restore_tag（Pro 和 Ultra）

找回已删除的标签。

参数	类型	说明
`tag`	string	必填

输入限制

字段	最大长度	用于
title	200 个字符	创建 / 更新笔记、任务、事件
description	2,000 个字符	创建 / 更新任务、事件
summary	1,000 个字符（硬性）	创建 / 更新笔记。会用于你的报告，所以请保持简短
transcript	取决于套餐：Pro 20,000 / Ultra 50,000	创建 / 更新笔记。长篇正文，不包含在报告中
text	取决于套餐：Pro 20,000 / Ultra 50,000（未发送音频时）	process_note
location	200 个字符	创建 / 更新事件
tags	20 个标签	创建 / 更新笔记、任务、事件
search query	500 个字符	search
audio_base64	约 7 MB 音频（整个请求限制为 10 MB）	process_note

如果超出限制，工具会返回类似 "title too long (max 200 chars, got 250)" 的错误消息。

错误处理

大多数工具会以 JSON 形式返回错误：

{"error": "description of what went wrong"}

套餐、scope 和输入限制方面的错误会以同样的消息作为工具错误返回。

常见错误：

错误	何时出现
`"This TellDone connection is read-only. Creating and editing needs the Pro or Ultra plan."`	在只读模式下调用了写入工具（Free 和 Basic，或切换到只读的 Pro 和 Ultra）
`"Daily limit reached: the Free plan includes 100 TellDone requests a day..."`	Free 套餐用完了当天的 100 次请求
`"Daily limit reached (N/M today)"`	你今天通过 AI 助手创建的条目已达到套餐允许的数量（process_note、create_note、create_task 和 create_event 各计一次）
`"Notes limit reached (X/Y this month)"`	你的套餐的每月笔记上限已用完
`"Invalid note_id format"`	传入了不是 UUID 的字符串作为 ID
`"Note not found"`	ID 不存在，或属于其他用户
`"Task not found or already completed"`	对不存在或已完成的任务调用 `complete_task`
`"title too long (max 200 chars, got N)"`	超出输入限制
`"Too many tags (max 20)"`	提供了超过 20 个标签

HTTP 层面的错误：

状态码	含义
401	令牌无效、已撤销或已删除（停用 MCP 会删除你的令牌，重新生成会替换它）
429	超出频率限制（5 次/秒，突发最多 20 次）

在 Free 上，达到每天 100 次请求的上限会以工具错误消息的形式报告（而不是 HTTP 状态码），并在你账户中保存的时区的午夜重置。

使用示例

所有示例都使用 cURL 和 MCP JSON-RPC 协议。请把 YOUR_TOKEN 替换为你的访问令牌。

读取数据

# Get your profile and stats
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"get_profile"}}'

# List recent notes (limit 5, from April 2026)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_notes","arguments":{"limit":5,"date_from":"2026-04-01"}}}'

# Search notes (hybrid text + semantic)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call",
       "params":{"name":"search","arguments":{"query":"project deadline","limit":5}}}'

写入数据（Pro 和 Ultra）

# Process a note through full AI pipeline (extracts tasks + events)
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":10,"method":"tools/call",
       "params":{"name":"process_note","arguments":{"text":"Need to buy groceries tomorrow. Meeting with Katie at 3pm at the cafe to discuss the project."}}}'

# Create a task with deadline and reminder
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":11,"method":"tools/call",
       "params":{"name":"create_task","arguments":{"title":"Review PR","priority":"high","deadline":"2026-04-15","reminder_at":"2026-04-15T09:00:00Z","tags":"dev"}}}'

# Create a repeating event with reminders and attendees
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":12,"method":"tools/call",
       "params":{"name":"create_event","arguments":{"title":"Team standup","start_at":"2026-04-12T10:00:00Z","reminder_minutes":"15","attendees":"Katie,John","recurrence_rule":"FREQ=DAILY;BYDAY=MO,TU,WE,TH,FR","tags":"meeting"}}}'

# Complete a task
curl -s -X POST https://api.telldone.app/mcp/user/mcp \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":13,"method":"tools/call",
       "params":{"name":"complete_task","arguments":{"task_id":"<task-uuid>"}}}'

成功的响应如下所示：

{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "content": [{"type": "text", "text": "{\"id\":\"...\",\"title\":\"Review PR\",\"status\":\"todo\"}"}]
  }
}

备注

写入和更新工具返回的响应很简短，主要是 id、title 和 status。删除工具返回 id 和 deleted。写入之后如果想获取完整详情（标签、优先级、截止日期等），请再发起一次读取调用，例如 get_tasks 或 get_note。

令牌管理

操作	方法
查看令牌	iPhone 上的设置 > 集成 > AI 智能体（MCP）> 面向开发者（在网页版上是设置 > 集成 > AI 智能体（MCP）），轻点显示
复制令牌	轻点令牌旁边的复制
重新生成	轻点重新生成令牌并确认。旧令牌会立即失效。通过 OAuth 登录连接的助手不受影响；请在已连接的应用下断开它们
更改模式	Pro 和 Ultra：选择只读或读写。Free 和 Basic 始终是只读
停用	轻点停用并确认（“所有已连接 AI 工具的访问权限将被撤销。”）。你的令牌会被删除，所有连接都会停止。如果你再次启用 MCP，会得到新的令牌，通过登录（OAuth）连接的 App 无需重新登录即可再次使用。要彻底移除某个 App，请在已连接的应用下轻点断开

你可以问你的 AI 智能体什么

连接后，可以向你的 AI 工具提出这样的问题：

回顾你的一天：

“我今天做了什么？”
“给我看看本周的笔记”
“哪些任务已经逾期？”

管理任务：

“创建一个任务：审阅季度报告，高优先级，周五截止”
“把 Figma 那个任务标记为完成”
“我正在做哪些任务？”

搜索和分析：

“找出所有关于营销策略的笔记”
“下周我有哪些事件？”
“总结一下我上周的每日报告”

提前规划：

“创建一个事件：明天上午 10 点的团队站会”
“我这周的日历上有什么？”
“给我看看我最常用的标签 - 我把最多时间花在什么上？”

你的助手可以读取你的笔记、任务、事件和报告，并通过综合多个工具的信息来回答复杂的问题。在 Pro 和 Ultra 上开启读写后，它还可以创建、更新和删除它们。

须知

集成和自动化 - process_note 的工作方式和录音一样，所以它的笔记、任务和事件会发送到你已连接的集成和 webhook 自动化。你用其他写入工具创建、编辑或删除的条目，表现和在 App 中完全一样：它们会到达你已连接的集成（事件和笔记的编辑只会到达 Notion）和你的自动化。用 restore_entity 恢复任务，或用 undo_change_log_entry 撤销任务的完成，也会在它已同步到的集成中重新打开该任务。
AI 助手所做的编辑 - 在条目的更改记录中，这些编辑会标明是由助手完成的。它们不会用于训练 TellDone 的语音识别，也不会复制到同一笔记的其他条目中。通过助手进行的编辑和 App 共用每分钟 30 次编辑的上限。
语义搜索 - 用 process_note 或 create_note 创建的笔记都会生成嵌入向量，所以稍等片刻后它们就会出现在语义搜索中。
日期筛选 - 对于笔记，日期是 UTC 日。对于事件，日期是你自己本地的日子，与范围重叠的事件也会包含在内。对于任务，筛选的是截止日期。

安全性

每位用户都有一个唯一的 384 位访问令牌
停用 MCP 或重新生成时，你的令牌会立即被撤销
每个请求都限定在你的账户范围内，所以你的智能体只能访问你自己的数据
连接使用 HTTPS，并有频率限制（5 次/秒，突发最多 20 次）
OAuth 连接使用 PKCE、一次性授权码和短期访问令牌 - 你可以随时在 App 中撤销连接

如需技术层面的深入介绍 - 发现端点、令牌有效期、完整的 OAuth 流程 - 请参阅我们的开源连接器参考 github.com/exp78/telldone-mcp，或者直接查询 https://api.telldone.app/.well-known/oauth-protected-resource。

隐私和数据流向

连接的 AI 工具只有在调用 TellDone 时才会获得你的数据，通常是因为你向它提了问题。它只会收到这些调用的答复，并且在你批准的权限范围内。要限制访问，请切换到只读，在已连接的应用下断开该 App，或者在设置中重新生成或停用你的访问令牌。详情请参阅隐私政策，也可以通过 support@telldone.app 联系我们提问。

故障排除

现象	原因 / 解决办法
OAuth 授权页面显示“邮箱或密码错误”	请使用你登录 App 时用的邮箱和密码，或者在同一页面选择通过 Apple 登录 / 使用 Google 登录。
已连接，但 AI 无法创建或编辑任何内容	你的套餐是 Free 或 Basic（只读），你的模式是只读，或者该连接没有写入权限。如果你是在升级之前连接的，请在已连接的应用下断开该 App，然后重新连接。你可以在设置中查看你的模式。
工具返回“Insufficient scope”错误	该连接没有那项权限。在 Free 和 Basic 上，永远不会授予写入权限，所以创建和编辑需要 Pro 或 Ultra。如果你是在升级之前连接的，请在已连接的应用下断开该 App，然后重新连接。
复制的代码片段里是 `YOUR_TOKEN`，客户端无法连接	你是在令牌隐藏时复制的。在面向开发者中，轻点显示，然后重新复制代码片段。
工具完全没有出现	你的账户没有启用 MCP（设置 > 集成 > AI 智能体（MCP）> 启用）。
“Daily limit reached”	有两种上限使用这条消息。“Daily limit reached: the Free plan includes 100 TellDone requests a day”是 Free 的请求上限。“Daily limit reached (N/M today)”表示你今天通过 AI 助手创建的条目已达到套餐允许的数量：process_note、create_note、create_task 和 create_event 各计一次，Pro 和 Ultra 也一样。两者都在你账户中保存的时区的午夜重置。
我的客户端只能从连接器列表中选择，而 TellDone 不在其中	TellDone 目前还没有进入任何客户端的连接器目录 - 请用 MCP URL 把它添加为自定义连接器，或使用 Bearer 令牌的方式。

另请参阅

Webhook 自动化 - 自动把数据发送到外部服务
Todoist - 专用的任务双向同步
Notion - 专用的 Notion 集成

两种连接方式​

套餐要求​

应用内屏幕​

如何启用​

通过 OAuth 连接​

ChatGPT​

Claude（网站、Desktop、iPhone App）/ Cowork​

通过 Bearer 令牌连接​

Claude Code（Bearer 令牌）​

Cursor​

其他客户端​

Codex​

OpenClaw​

其他 MCP 客户端​

测试你的连接​

权限（scope）​

你可以做什么​

读取工具（10 个）- 所有套餐​

写入工具（17 个）- Pro 和 Ultra​

工具参考​

get_notes​

get_note​

get_notes_full​

get_tasks​

get_events​

get_reports​

get_tags​

get_profile​

search​

get_change_log​

process_note（Pro 和 Ultra）​

create_note（Pro 和 Ultra）​

create_task（Pro 和 Ultra）​

create_event（Pro 和 Ultra）​

update_note（Pro 和 Ultra）​

update_task（Pro 和 Ultra）​

complete_task（Pro 和 Ultra）​

update_event（Pro 和 Ultra）​

delete_note（Pro 和 Ultra）​

delete_task（Pro 和 Ultra）​

delete_event（Pro 和 Ultra）​

undo_change_log_entry（Pro 和 Ultra）​

restore_entity（Pro 和 Ultra）​

create_tag（Pro 和 Ultra）​

set_tag_pinned（Pro 和 Ultra）​

delete_tag（Pro 和 Ultra）​

restore_tag（Pro 和 Ultra）​

输入限制​

错误处理​

使用示例​

读取数据​

写入数据（Pro 和 Ultra）​

令牌管理​

你可以问你的 AI 智能体什么​

须知​

安全性​

隐私和数据流向​

故障排除​

另请参阅​