跳到主要内容

MCP 访问(AI agents)

最近的变化

MCP 现在在 iPhone 上也完全可用(除了网页版)。iPhone 屏幕镜像了网页版,并包含所有支持 AI 客户端的相同设置代码片段。

Pro 套餐及以上

MCP 访问需要 Pro 或 Ultra 套餐。两个套餐都获得完整的读 + 写访问(20 个工具)。Ultra 拥有更高的配额,并可切换到只读模式。

MCP(Model Context Protocol)让你把 AI 编码助手和自动化工具直接连接到你的 TellDone 数据。连接后,你的 AI agent 可以读取你的笔记、任务、事件和报告,并创建、更新和删除条目。共有 20 个工具:9 个用于读取数据,11 个用于写入。

iPhone 应用(设置 → 集成 → AI Agents)和网页版(设置 → AI Agents)中均可使用。

套餐要求

套餐MCP
Free锁定
Basic锁定
Pro读 + 写(20 个工具)
Ultra读 + 写(20 个工具,更高配额) - 也可切换到只读模式

应用内屏幕

AI Agents 屏幕根据你的套餐和 MCP 是否打开有三种状态。

锁定(Free 和 Basic)

如果你在 Free 或 Basic 套餐上,屏幕会说明 MCP 的功能并显示升级按钮。点按它会打开付费墙,让你升级到 Pro 或 Ultra。

已禁用(Pro 和 Ultra,功能未开)

如果你在 Pro 或 Ultra 上但还没有打开 MCP,屏幕会显示你套餐能做什么的简短摘要(工具数量、访问模式、配额)和一个启用按钮。点按它生成你的连接令牌并启动集成。

已启用

启用后,屏幕显示连接 AI 客户端所需的一切:

  • 模式开关 - 在 Ultra 上你可以在只读读 + 写之间切换。在 Pro 上模式固定为读 + 写
  • 访问令牌行带有眼睛图标用于显示或隐藏令牌,并有复制按钮。
  • 设置选择器带有 Claude CodeCursorWindsurf其他标签页。匹配的代码片段出现在标签页下方 - 复制粘贴到你的 AI 客户端即可。
  • 重新生成按钮 - 立即轮换令牌,并断开使用旧令牌的所有活动会话。
  • 禁用按钮 - 关闭 MCP 并删除令牌。你可以稍后重新启用,但会签发新令牌。
提示

请将连接令牌保密。任何拥有令牌的人都可以访问你的 TellDone 数据。如果你怀疑令牌泄露,请使用重新生成

如何启用

你可以从任一平台配置 MCP:

  • iPhone: 设置 → 集成 → AI Agents(MCP)
  • 网页: app.telldone.app → 设置 → AI Agents

步骤:

  1. 点按启用
  2. 选择你的访问模式(仅 Ultra - Pro 始终为读 + 写)。
  3. 用眼睛和复制图标显示并复制你的令牌。
  4. 设置部分选择你的工具(Claude Code、Cursor、Windsurf 或其他)。
  5. 把代码片段粘贴到你的 AI 客户端配置中。

连接你的 AI 工具

应用内设置选择器的四个标签页(Claude Code、Cursor、Windsurf、其他)对应下面的部分。所有示例中把 YOUR_TOKEN 替换为你设置中的令牌。

Claude Code

在终端运行此命令:

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

Cursor

添加到 .cursor/mcp.json

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

Windsurf

添加到 .codeium/windsurf/mcp_config.json

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

其他

应用内选择器归在其他下的客户端使用这些代码片段。

Codex

添加到 codex.json

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

OpenClaw

设置 > MCP Servers > 添加:

  • 名称:TellDone
  • URL:https://api.telldone.app/mcp/user/mcp
  • 认证: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}'

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

你能做什么

读工具(9) - Pro 和 Ultra

工具作用
get_notes列出笔记,支持筛选(标签、日期范围、文本搜索)
get_note查看单条笔记,包括子任务、事件和完整转录文本
get_notes_full一次调用获取多条笔记,附带嵌入的任务和事件
get_tasks按状态(待办、已完成、全部)、标签或日期筛选任务
get_events列出日历事件,按日期范围筛选
get_reports读取你的每日、每周、每月和每年报告(完整 markdown)
get_tags查看你所有标签,按使用情况排序
get_profile查看你的账户信息和使用统计
search跨笔记、任务和事件搜索(笔记支持文本 + 语义搜索)
提示

search 工具支持笔记的语义搜索 - 它按含义查找结果,不仅仅是关键词。例如搜索「关于预算的会议」会找到关于财务讨论的笔记,即便它们不包含「预算」一词。

写工具(11) - 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删除事件

所有写入和删除操作通过实时同步立即出现在你已连接的设备上(手机、网页版)。

工具参考

get_notes

列出笔记,支持可选筛选。日期筛选使用 recorded_at(你录制语音笔记的时间),不是 created_at

参数类型默认说明
limitint20返回的笔记数(最多 50)
offsetint0跳过这么多笔记(用于分页,最多 10000)
tagsstring-按标签筛选,逗号分隔(任一匹配)
searchstring-在标题和摘要上文本搜索
date_fromstring-起始日期,YYYY-MM-DD(包含)
date_tostring-结束日期,YYYY-MM-DD(不包含)

返回:笔记列表,包含 idtitlesummarytypetagsprioritystatusrecorded_atcreated_at

get_note

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

参数类型说明
note_idstring笔记的 UUID

返回:笔记,包含 titlesummarytranscripttypetagsprioritystatusmetadatacreated_at,以及 tasks[]events[] 数组。

get_notes_full

一次调用获取多条笔记及其任务和事件。筛选条件与 get_notes 相同,但每条笔记包含嵌入的 tasks[]events[]

参数类型默认说明
limitint10笔记数量(最多 20)
offsetint0跳过这么多笔记
tagsstring-按标签筛选
date_fromstring-起始日期,YYYY-MM-DD
date_tostring-结束日期,YYYY-MM-DD

get_tasks

列出任务,支持筛选。

参数类型默认说明
statusstring"todo"筛选:tododoneall
limitint30任务数量(最多 100)
offsetint0跳过这么多任务
tagsstring-按标签筛选,逗号分隔
date_fromstring-起始日期,YYYY-MM-DD(按截止时间筛选;没有截止时间的任务会被排除)
date_tostring-结束日期,YYYY-MM-DD(按截止时间筛选;没有截止时间的任务会被排除)

返回:任务列表,包含 idtitledescriptionstatusprioritytagsdeadlinereminder_atcompleted_atcompleted_bysourcecreated_at

get_events

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

参数类型默认说明
limitint30事件数量(最多 100)
offsetint0跳过这么多事件
date_fromstring-起始日期,YYYY-MM-DD(按事件开始时间筛选)
date_tostring-结束日期,YYYY-MM-DD

返回:事件列表,包含 idtitledescriptionstatusstart_atend_atlocationis_all_daytagscreated_at

备注

get_events 不返回 attendeesreminder_minutesrecurrence_rule。这些可以通过 create_event/update_event 写入,但不包含在列表输出中。如需获取,请用 get_note 取父级笔记。

get_reports

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

参数类型默认说明
report_typestring"daily"类型:dailyweeklymonthlyyearly
limitint5报告数量(最多 10)

返回:报告列表,包含 idtypeperiod_startperiod_endcontent_mdcreated_at

备注

月度报告可能有 3,000-5,000 字。如果你的 AI 工具上下文窗口紧张,请使用 limit=1

get_tags

获取你所有的标签,已置顶的优先,然后按使用次数排序。

无参数。返回最多 100 个标签,每个包含 tagusage_countis_pinnedis_manual

get_profile

获取你的账户信息和使用统计。

无参数。返回 emaildisplay_namelocaletranscription_localetimezonesubscriptionmcp_modecreated_at,以及 stats(笔记/任务/事件计数)。

跨笔记、任务和事件一次搜索。对笔记同时支持文本搜索和语义搜索(使用 AI 嵌入按含义查找结果)。

参数类型默认说明
querystring必填搜索文本(最多 500 字符)
limitint20每种类型的最大结果数(最多 20)
semanticbooltrue为笔记启用语义搜索

返回按类型分组的结果:notes[]tasks[]events[]。每个结果包含 idtypetitledetailcreated_at

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

process_note(Pro 和 Ultra)

完整 AI 流水线 - 与在应用中录音相同。发送文本或音频,TellDone 会转录、用 AI 分析,并创建一条带提取的任务、事件、标签和嵌入的结构化笔记。

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

参数类型说明
textstring要分析的文本(如果未提供音频则跳过转录)
audio_base64stringBase64 编码的音频文件(最多 50MB,触发转录)
audio_formatstringm4aoggwavmp3aacwebm(默认:m4a)
parent_task_idstring跟进的任务的 UUID
parent_note_idstring跟进的笔记的 UUID
parent_event_idstring跟进的事件的 UUID

你必须提供 textaudio_base64(或两者都提供 - 转录优先用音频)。

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

备注

process_note 受你套餐配额限制(每日上传次数、每月笔记数、最大文本长度)。使用 get_profile 检查当前用量。

create_note(Pro 和 Ultra)

立即创建一条纯文本笔记。不会触发 AI 分析 - 不会提取任务或事件。如需带任务/事件提取的完整 AI 分析,请改用 process_note

参数类型限制说明
titlestring200 字符必填
summarystring1000 字符可选。简短预览(1-3 句)。包含在报告提示中,请保持简洁
transcriptstring按套餐可选。在笔记详情中显示的长文本正文。不包含在报告中。限制:Free 2,000 / Basic 8,000 / Pro 20,000 / Ultra 50,000 字符
typestring-可选。taskideainfo(默认)、statusmeetingeventreflection
tagsstring20 个标签逗号分隔,可选

create_task(Pro 和 Ultra)

创建一个新任务。

参数类型限制说明
titlestring200 字符必填
descriptionstring2000 字符可选
prioritystring-lowmedium(默认)或 high
deadlinestring-YYYY-MM-DD,可选
reminder_atstring-ISO 8601 日期时间(例如 2026-04-15T09:00:00Z),可选
tagsstring20 个标签逗号分隔,可选
note_idstring-把任务关联到父级笔记的 UUID,可选

create_event(Pro 和 Ultra)

创建一个日历事件。

参数类型限制说明
titlestring200 字符必填
start_atstring-ISO 8601 日期时间,必填
end_atstring-ISO 8601 日期时间(默认:start + 1 小时)
descriptionstring2000 字符可选
locationstring200 字符可选
is_all_daybool-默认:false
tagsstring20 个标签逗号分隔,可选
reminder_minutesstring-事件前的分钟数,逗号分隔(例如 15,60),可选
attendeesstring-名字或邮箱,逗号分隔,可选
recurrence_rulestring-RRULE 字符串(例如 FREQ=WEEKLY;BYDAY=MO,WE,FR),可选
note_idstring-把事件关联到父级笔记的 UUID,可选

update_note(Pro 和 Ultra)

更新现有笔记的一个或多个字段。只有你提供的字段会被更改。

参数类型说明
note_idstring必填,笔记的 UUID
titlestring新标题(最多 200 字符)
summarystring新摘要(最多 1000 字符,传入空格 " " 可清空)
transcriptstring新转录(按套餐限制,传入空格 " " 可清空)
typestringtaskideainfostatusmeetingeventreflection
tagsstring逗号分隔的标签(替换所有现有标签,最多 20)
prioritystringlowmediumhigh
statusstringactivearchived
警告

对于由语音流水线创建的笔记,transcript 是原始的语音转文字输出。覆盖它会替换权威源 - 如果想保留原始内容,请考虑在其后追加。

update_task(Pro 和 Ultra)

更新现有任务的一个或多个字段。只有你提供的字段会被更改。

参数类型说明
task_idstring必填,任务的 UUID
titlestring新标题
descriptionstring新描述(传入空格 " " 可清空)
prioritystringlowmediumhigh
deadlinestringYYYY-MM-DD(传入空格可清空)
statusstringtododone
tagsstring逗号分隔的标签(替换所有现有标签,最多 20)
reminder_atstringISO 8601 日期时间(传入空格可清空)

status 设为 done 也会记录任务何时以及如何完成。

complete_task(Pro 和 Ultra)

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

参数类型说明
task_idstring必填,任务的 UUID

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

update_event(Pro 和 Ultra)

更新现有事件的一个或多个字段。只有你提供的字段会被更改。

参数类型说明
event_idstring必填,事件的 UUID
titlestring新标题
descriptionstring新描述(传入空格可清空)
start_atstring新开始时间(ISO 8601)
end_atstring新结束时间(ISO 8601)
locationstring新地点(传入空格可清空)
statusstringconfirmedtentativecancelled
tagsstring逗号分隔的标签(替换所有现有标签,最多 20)
is_all_daystring"true""false"
reminder_minutesstring事件前的分钟数,逗号分隔(例如 15,60
attendeesstring名字或邮箱,逗号分隔
recurrence_rulestringRRULE 字符串(传入空格可清空)

delete_note(Pro 和 Ultra)

删除一条笔记。这也会删除从此笔记创建的所有任务和事件。

参数类型说明
note_idstring必填,笔记的 UUID

delete_task(Pro 和 Ultra)

删除一个任务。

参数类型说明
task_idstring必填,任务的 UUID

delete_event(Pro 和 Ultra)

删除一个事件。

参数类型说明
event_idstring必填,事件的 UUID

输入限制

字段最大长度用于
title200 字符创建/更新 笔记、任务、事件
description2,000 字符创建/更新 任务、事件
summary1,000 字符(硬限)创建/更新 笔记。包含在报告提示中,保持简短以控制 token 成本
transcript按套餐:Free 2,000 / Basic 8,000 / Pro 20,000 / Ultra 50,000创建/更新 笔记。长文本正文,不在报告中
location200 字符创建/更新 事件
tags20 个标签创建/更新 笔记、任务、事件
搜索查询500 字符search
audio_base64(解码后)50 MBprocess_note

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

错误处理

所有工具都返回 JSON。错误使用以下格式:

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

常见错误:

错误何时出现
"MCP access is read-only..."在只读模式下调用了写工具
"Invalid note_id format"传入的 ID 不是 UUID 字符串
"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 级别错误:

代码含义
401Bearer 令牌无效或缺失
403MCP 已禁用或套餐不允许 MCP
429超出速率限制(5 req/s)

使用示例

所有示例使用 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 recurring 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": 10,
"result": {
"content": [{"type": "text", "text": "{\"id\":\"...\",\"title\":\"Review PR\",\"status\":\"todo\"}"}]
}
}
备注

写和更新工具返回最小响应,仅包含 idtitlestatus。要在写入后获取完整详情(标签、优先级、截止时间等),请进行后续的读取调用,如 get_tasksget_note

令牌管理

操作如何
查看令牌iPhone「设置 → 集成 → AI Agents」(或网页「设置 → AI Agents」),点按眼睛图标
复制令牌点按令牌旁的复制图标
重新生成点按重新生成并确认。旧令牌立即失效,所有活动会话断开
更改模式仅 Ultra - 在只读和读 + 写之间切换。在 Pro 上模式固定为读 + 写
禁用点按禁用并确认。令牌被删除,所有连接停止。你可以稍后重新启用(会签发新令牌)

你可以让 AI agent 做什么

连接后,让你的 AI 工具做这些事:

回顾你的一天:

  • 「我今天做了什么?」
  • 「显示我本周的笔记」
  • 「哪些任务逾期了?」

管理任务:

  • 「创建任务:审阅季度报告,高优先级,截止周五」
  • 「把 Figma 任务标记为完成」
  • 「我在做哪些任务?」

搜索和分析:

  • 「找到所有关于营销策略的笔记」
  • 「我下周有哪些事件?」
  • 「总结我上周的每日报告」

提前规划:

  • 「创建事件:明天上午 10 点团队 standup」
  • 「我本周日历上有什么?」
  • 「显示我的热门标签 - 我把最多时间花在了哪里?」

AI agent 拥有对你笔记、任务、事件和报告的完整访问。它可以读、创建、更新和删除数据,并通过组合多个工具的信息回答复杂问题。

重要说明

  • 创建笔记的两种方式 - create_note 立即创建纯文本笔记(不进行 AI 分析)。process_note 运行完整的 AI 流水线(与在应用中录音相同) - 它分析文本、提取任务和事件、生成标签和嵌入。当你想让 TellDone 替你思考时使用 process_note
  • 不触发集成同步 - 通过 MCP 创建或更新的条目不会触发 Webhook 自动化或集成同步(Todoist、Notion)。它们会在下一次同步时出现在你的应用中。
  • 语义搜索取决于工具 - 用 process_note 创建的笔记会获得嵌入并出现在语义搜索中。用 create_note 创建的笔记不会获得嵌入,所以仅出现在文本搜索中。
  • 写响应是最小化的 - 创建和更新工具仅返回 idtitlestatus。要在写入后获取所有字段,请进行后续的读取调用。
  • 日期筛选使用 UTC - date_from/date_to 参数按 UTC 时间戳比较。对于非 UTC 时区的用户,边界日期可能包含或排除相邻日期的条目。
  • 速率限制 - 每秒 5 个请求。批量操作请控制速度。

安全

  • 每个用户获得唯一的 384 位连接令牌
  • 当你禁用 MCP 或重新生成令牌时,你的令牌立即被吊销
  • 所有数据严格隔离到你的账户 - 你的 agent 只能访问你自己的数据
  • 每个请求都限定在你的用户范围 - agent 无法访问其他用户的数据
  • 连接使用 HTTPS 并带速率限制(5 req/s)

另见