telldone

TellDone MCP 服务

将你的 TellDone 语音笔记、任务、事件和报告连接到 Claude（桌面版、claude.ai 和 Code）、Cursor、Windsurf、Codex 以及任何兼容 MCP 的客户端——支持一键 OAuth（通过浏览器登录，无需复制令牌）或持有者令牌。

TellDone 是一款语音优先的规划应用。口述想法后，AI 会自动将其整理为结构化笔记、任务、事件和每日效率报告。

iOS 和 Apple Watch 上均可进行语音录制。Android 版即将推出。你也可以通过 MCP 使用 process_note 发送文本，进入相同的 AI 分析流程。

注册后使用促销码 MCPBETA26，即可免费使用 MCP（30 天内可读写，之后一年内只读）。

快速开始

通过以下两种方式之一进行连接：一键 OAuth（推荐——通过浏览器登录，无需复制任何内容）或持有者令牌（适用于所有 MCP 客户端）。

选项 A — 一键 OAuth · Claude Desktop、claude.ai、Claude Code

将 TellDone 添加为连接器，在浏览器中登录账户并批准访问。访问令牌有效期较短、权限范围有限，且可随时在设置中撤销——无需复制或存储任何内容。

Claude Desktop 和 claude.ai — 在设置中打开连接器，选择添加自定义连接器，然后粘贴：

https://api.telldone.app/mcp/user

点击连接，登录 TellDone 并批准访问。无需手动注册应用——TellDone 支持 Client ID Metadata Documents，因此 Claude 会自动完成注册。

Claude Code

claude mcp add --transport http telldone https://api.telldone.app/mcp/user

然后运行 /mcp 并选择 telldone → Authenticate，在浏览器中打开 TellDone 授权页面——登录并批准一次即可。（CLI v2.1.186+：在 Shell 中运行 claude mcp login telldone，效果相同。）

任何支持 OAuth 2.1 发现机制（RFC 9728 + RFC 8414）的 MCP 客户端都可以用相同方式连接。

选项 B — 持有者令牌 · Cursor、Windsurf、Codex 或任何客户端

先获取令牌：在 app.telldone.app 注册，打开设置 → AI Agents (MCP)，然后点击启用。接着使用你的令牌添加服务：

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 服务 > 添加 > 名称：TellDone，URL：https://api.telldone.app/mcp/user/mcp，身份验证：Bearer YOUR_TOKEN

开始使用

可以向你的 AI 工具提出以下问题：

• “我今天做了哪些工作？”
• “创建一个任务：审阅季度报告，优先级高，截止日期为星期五”
• “查找所有关于营销策略的笔记”
• “将 Figma 任务标记为已完成”
• “创建一个事件：明天上午 10 点举行团队每日站会，提前 15 分钟提醒我”
• “处理这份会议摘要并提取任务”
• “我下周有哪些事件？”
• “显示我昨天的每日报告”

数据格式 — 解析输出前请先阅读

每个工具都会返回 JSON。MCP 线协议响应会将负载包装在 result.content[0].text 中，作为一个JSON 编码字符串——使用 json.loads()（或同等方法）解析，才能获取实际数据。

解码后的 JSON 中，所有日期时间、日期和 UUID 都是字符串，而非原生语言类型。 不要直接对它们调用 .toordinal()、.weekday() 或任何日期时间方法——否则会得到 TypeError: 'str' has no attribute 'toordinal'。请先解析它们。

标量输出类型

字段形态	线协议格式	示例	解析方式
UUID	字符串（小写十六进制，带连字符）	"b3f3c8a0-9a4d-4e12-9f4a-1a1b2c3d4e5f"	原样使用
日期时间（时间戳）	带时区偏移的 ISO 8601 字符串	"2026-04-18T11:30:00+00:00"	Python 中使用 datetime.fromisoformat(s)；JS 中使用 new Date(s)
日期（不含时间的日历日期）	YYYY-MM-DD 字符串	"2026-04-18"	Python 中使用 date.fromisoformat(s)
布尔值	true / false	true	原生类型
整数	JSON 数字	42	原生类型
可空字段	JSON null	null	None / null

数组／对象输出类型

字段	传输格式
tags（用于 notes/tasks/events）	字符串数组；如果从未设置，则为 null；如果已清除，则为 []
reminder_minutes（events，可写字段）	输入／输出均为整数数组
attendees（events，可写字段）	字符串数组（姓名／邮箱）
metadata（notes）	JSON 对象或 null
get_note／get_notes_full 中的 tasks／events 数组	始终存在，可能为空 []

枚举值

• priority — "low"、"medium"、"high" 或 null
• note.type — "task"、"idea"、"info"、"status"、"meeting"、"event"、"reflection"
• note.status — "active"、"archived"（已删除的记录不会包含在任何读取工具的结果中）
• task.status — "todo"、"done"（查询参数 status="all" 表示“所有未删除的记录”）
• event.status — "confirmed"、"tentative"、"cancelled"
• report.type — "daily"、"weekly"、"monthly"、"yearly"
• source（tasks）、completed_by（tasks）——自由格式字符串："mcp"、"app"、"sync"、"audio"、"todoist"、"notion" 等

各工具的输出字段

工具	返回字段（除特别说明外，均位于每个数组项的顶层）
get_profile	id UUID、email str、display_name str|null、locale str、transcription_locale str|null、timezone str（IANA）、subscription str、mcp_mode str、created_at ISO 8601 datetime str、stats {notes:int, tasks:int, events:int}
get_notes	id UUID、title str、summary str|null、type enum、tags str[]|null、priority enum|null、status enum、recorded_at ISO 8601 datetime str|null、created_at ISO 8601 datetime str
get_note	note 字段（id、title、summary、transcript str|null、type、tags、priority、status、metadata obj|null、created_at）+ 包含部分字段的 tasks[] + events[] 数组
get_notes_full	包含内嵌 tasks[] 和 events[] 的 notes 数组（与 get_note 中的字段子集相同，但不含 metadata）
get_tasks	id UUID、title str、description str|null、status enum、priority enum|null、tags str[]|null、deadline YYYY-MM-DD str|null、reminder_at ISO 8601 datetime str|null、completed_at ISO 8601 datetime str|null、completed_by str|null、source str|null、created_at ISO 8601 datetime str
get_events	id UUID、title str、description str|null、status enum、start_at ISO 8601 datetime str（非空）、end_at ISO 8601 datetime str（非空）、location str|null、is_all_day bool|null、tags str[]|null、created_at ISO 8601 datetime str。注意：attendees、reminder_minutes、recurrence_rule 可通过 create_event／update_event 写入，但 get_events 不会返回这些字段。
get_reports	id UUID、type enum、period_start YYYY-MM-DD str、period_end YYYY-MM-DD str、content_md str|null、created_at ISO 8601 datetime str
get_tags	tag str、usage_count int、is_pinned bool、is_manual bool
search	{notes: [...], tasks: [...], events: [...]}——每个项目的格式为 {id UUID, type "note"/"task"/"event", title str, detail str|null, created_at ISO 8601 datetime str}。三个数组始终存在，可能为空。
写入工具	最少字段：{id UUID, title str, status enum}（notes 另含 type）。不要期待返回完整记录——如需更多字段，请调用对应的 get_* 工具。
删除工具	{id UUID, deleted: true}
process_note	{audio_id UUID, status "processing", mode "audio+stt"/"text-only", message str}——异步；最终结果会通过 WebSocket note_ready 发送，或在之后调用 get_notes 时返回。
任意工具出错时	{error: "message"}——在将响应视为记录之前，务必检查 error 键是否为 null。

输入参数格式

• note_id、task_id、event_id、parent_*_id — UUID 字符串
• date_from、date_to、deadline — YYYY-MM-DD 字符串（空字符串表示“不过滤”）
• start_at、end_at、reminder_at — ISO 8601 日期时间字符串，例如 "2026-04-15T09:00:00Z" 或 "2026-04-15T09:00:00+00:00"
• tags — 输入时为逗号分隔的字符串（例如 "work,urgent"）；存储/返回时为 string[]
• reminder_minutes、attendees — 输入时为逗号分隔的字符串；存储/返回时为数组
• is_all_day — 在 create_event 中为布尔值；在 update_event 中为字符串 "true"/"false"
• recurrence_rule — RRULE 字符串，例如 "FREQ=WEEKLY;BYDAY=MO,WE,FR"

解析示例（Python）

import json
from datetime import datetime, date

# tools/call response → text → decode
payload = json.loads(response["result"]["content"][0]["text"])

# Check for error first
if "error" in payload:
    raise RuntimeError(payload["error"])

# Events: start_at is a STRING like "2026-04-18T11:30:00+00:00"
for e in payload:   # payload is list from get_events
    start = datetime.fromisoformat(e["start_at"])   # -> tz-aware datetime
    if e["end_at"]:
        end = datetime.fromisoformat(e["end_at"])

# Tasks: deadline is a STRING like "2026-04-18" (date only)
for t in tasks_payload:
    if t["deadline"]:
        d = date.fromisoformat(t["deadline"])
        days_left = (d - date.today()).days

笔记字段：title、summary、transcript

每条笔记都有三个文本字段，各自的用途和限制均不同。选择正确的字段很重要——使用 create_note 或 update_note 时，LLM 客户端（Claude Desktop、Cursor 等）应合理拆分内容。

字段	用途	限制	是否包含在报告的 LLM 提示词中？
title	在列表、预览、推送和邮件主题中显示的单行主题。	200 个字符	✅（作为列表标题）
summary	1–3 句话的内容预告。	硬性上限为 1000 个字符——产品决策。	✅ 原样包含。 请保持简洁。
transcript	笔记的完整正文。显示在详情视图中。	根据套餐而定（见下文）	❌ 从不包含。可以较长。

根据套餐设定的 transcript 限制（subscription_plans.max_text_length）：

套餐	transcript 最大字符数
Free	2 000
Basic	8 000
Pro	20 000
Ultra	50 000
Custom	100 000

给 LLM 客户端的经验法则：

• **简短内容（笔记、提醒、待办事项）：**只填写 title + summary。将 transcript 留空。
• 较长内容（会议笔记、草稿、头脑风暴、研究资料）：填写 1–3 句话的 summary，并将完整正文放入 transcript。不要把所有内容都塞进 summary——否则会触发 1000 字符错误。

超限错误消息：

• summary too long (max 1000 chars, got N). For long-form content use the 'transcript' parameter (plan-based limit).
• transcript too long (max 20000 chars for pro plan, got N)

正确用法示例（Claude Desktop 记录一场会议）：

create_note({
  title: "Weekly engineering sync — API versioning",
  summary: "Team agreed on semver deprecation policy with 6-month sunset window. Owner: Alex. Next sync: Thu.",
  transcript: "Full meeting transcript: Alice raised the question of how to deprecate v1...\n\n[... 5 KB of detail ...]",
  tags: "engineering,versioning,meeting"
})

为什么有两种不同的上限？

• summary 会原样包含在每日/每周/每月报告的 LLM 提示词中。如果每条 summary 都可能达到 20 KB，报告提示词就会显著增加成本和延迟（重度用户还可能导致上下文窗口溢出）。2026 年 4 月，在测量生产数据后设定了 1000 个字符的上限（中位数为 247，最大值为 554）。
• transcript 从不包含在报告提示词中——它只会显示在 UI 详情视图中。较长的 transcript 只会占用存储空间，不会消耗 LLM 令牌。按套餐设定上限可防止滥用，同时也允许内容尽可能详尽。

向后兼容性：transcript 是可选参数（默认值为 ""）。调用 create_note(title, summary, tags, type) 的旧客户端仍可照常工作——数据库会将 transcript 存储为 NULL。无需迁移。

---

工具（20）

所有工具都包含 MCP 注解——title、readOnlyHint、destructiveHint、idempotentHint、openWorldHint——以便 MCP 客户端显示相应的确认界面。每个工具仅针对 Telldone 数据库运行（openWorldHint: false）——服务绝不会调用外部 API。

读取工具（9 个）

工具	描述
get_profile	返回已通过身份验证的用户资料，包括显示名称、电子邮件、区域设置、时区、订阅套餐和使用统计信息（笔记、任务、事件总数）。用于检查账户状态或配额。
get_notes	列出语音笔记，可选筛选条件：date_from/date_to（ISO 8601）、tag（字符串）、type（task/idea/info/status/meeting/event/reflection）、search（文本查询）、limit（默认 20，最大 100）、offset。返回笔记元数据，不含完整正文；如需查看详情，请使用 get_note。
get_note	根据 UUID note_id 返回单条笔记，包括完整转录、AI 摘要以及所有关联的子任务和事件。在通过 get_notes 或 search 找到笔记后，如需查看完整内容，请使用此工具。
get_notes_full	批量检索包含嵌套子项（任务 + 事件）的笔记。筛选条件与 get_notes 相同。可替代循环调用 get_note。返回的数据量较大，请合理设置 limit。
get_tasks	列出任务，可按以下条件筛选：status（todo/done/all，默认：todo）、tag、priority（low/medium/high）、截止日期范围 date_from/date_to、limit、offset。返回标题、优先级、截止日期、reminder_at、标签和完成状态。
get_events	列出日历事件，可按 date_from/date_to 日期范围、status（confirmed/tentative/cancelled）、limit、offset 筛选。返回事件标题、开始/结束时间、地点、参与者和提醒。
get_reports	返回 AI 生成的效率报告。可按 period（daily/weekly/monthly/yearly）和 date_from/date_to 筛选。报告总结已完成的任务、规律和效率洞察。
get_tags	按使用频率（最常用的排在前面）返回用户定义的所有标签。无需参数。筛选笔记或任务前，可用此工具查看可用标签。
search	对笔记、任务和事件进行文本 + 语义混合搜索。参数：query（字符串）。结合关键词匹配与向量相似度，即使措辞不同也能返回相关结果。返回包含相关性分数的多种结果类型。

写入工具（11 个）

工具	描述
process_note	对文本或音频输入运行完整的 AI 分析流程，与在移动应用中录制语音笔记完全相同。接受 text（字符串），或 audio_base64 + audio_format（m4a/wav/mp3）。AI 会提取结构化笔记、任务、事件和标签。立即返回 audio_id；结果将异步送达。使用 get_notes() 轮询以获取处理结果。
create_note	创建纯文本笔记，不进行 AI 分析。参数：title（必填，最多 200 字符）、summary（最多 1000 个字符，简洁预告内容——会包含在报告 LLM 提示词中）、transcript（基于套餐的限额，长篇正文——不会包含在报告提示词中）、type（task/idea/info/status/meeting/event/reflection）、tags（逗号分隔，最多 20 个）。长文本应放在哪里，请参阅 笔记字段 部分。
create_task	创建任务，包含 title（必填）、description、priority（low/medium/high，默认值：medium）、deadline（ISO 8601 日期）、reminder_at（ISO 8601 日期时间）、tags（逗号分隔）。任务创建时的状态为 "todo"。实时同步到移动应用。
create_event	创建日历事件，包含 title（必填）、start_at/end_at（ISO 8601 日期时间）、location、attendees（逗号分隔）、reminder_minutes（整数）、recurrence（rrule 字符串）、status（confirmed/tentative）。
update_note	根据 note_id（UUID，必填）更新笔记字段。可选：title、summary（最多 1000 个字符）、transcript（基于套餐的限额，长篇正文）、type、tags、priority、status。仅修改提供的字段；未提供的字段保持不变。传入 " "（单个空格）可清空 summary 或 transcript 字段。
update_task	根据 task_id（UUID，必填）更新任务字段。可选：title、description、priority、deadline、reminder_at、tags、status（todo/done）。可使用 complete_task 快捷地将任务标记为完成。
update_event	根据 event_id（UUID，必填）更新事件字段。可选：title、start_at、end_at、location、attendees、status（confirmed/tentative/cancelled）、reminder_minutes。
complete_task	根据 task_id（UUID）将任务标记为完成。相当于将 update_task 的 status 设为 "done"。记录完成时间戳和来源（"mcp"）。
delete_note	根据 note_id（UUID）软删除笔记。会级联删除所有关联的子任务和事件——它们也会被软删除。可在 Web 应用中撤销。
delete_task	根据 task_id（UUID）软删除任务。不会影响父笔记。可在 Web 应用中撤销。
delete_event	根据 event_id（UUID）软删除事件。不会影响父笔记。可在 Web 应用中撤销。

所有写入工具都会通过 WebSocket 实时同步到已连接的移动端和 Web 客户端。

完整流程：process_note

process_note 工具运行的流程与在移动应用中录制时相同：

Text or Audio --> STT (if audio) --> LLM Analysis --> Note + Tasks + Events + Tags

文本模式（跳过 STT）：

{"name": "process_note", "arguments": {"text": "Need to buy groceries. Meeting with Katie at 3pm."}}

音频模式（base64 编码）：

{"name": "process_note", "arguments": {"audio_base64": "...", "audio_format": "m4a"}}

立即返回 audio_id。结果会通过 WebSocket 送达，也可以使用 get_notes() 轮询获取。

示例

examples/test-connection.sh

#!/bin/bash
# Test your TellDone MCP connection
TOKEN="${1:?Usage: ./test-connection.sh YOUR_TOKEN}"
URL="https://api.telldone.app/mcp/user/mcp"

echo "=== Testing connection ==="
curl -s -X POST "$URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_profile"}}' \
  | python3 -m json.tool

echo ""
echo "=== Listing tools ==="
curl -s -X POST "$URL" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | python3 -c "import sys,json; tools=json.load(sys.stdin).get('result',{}).get('tools',[]); print(f'{len(tools)} tools available'); [print(f'  {t[\"name\"]}') for t in tools]"

examples/daily-summary.sh

#!/bin/bash
# Get today's tasks and notes summary
TOKEN="${1:?Usage: ./daily-summary.sh YOUR_TOKEN}"
URL="https://api.telldone.app/mcp/user/mcp"
TODAY=$(date +%Y-%m-%d)

call() {
  curl -s -X POST "$URL" \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -H "Accept: application/json" \
    -d "$1"
}

echo "=== Today's Notes ($TODAY) ==="
call "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"get_notes\",\"arguments\":{\"date_from\":\"$TODAY\",\"limit\":20}}}" \
  | python3 -c "
import sys, json
r = json.loads(json.load(sys.stdin)['result']['content'][0]['text'])
for n in r: print(f'  [{n[\"type\"]}] {n[\"title\"]}')" 2>/dev/null

echo ""
echo "=== Active Tasks ==="
call '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_tasks","arguments":{"status":"todo","limit":10}}}' \
  | python3 -c "
import sys, json
r = json.loads(json.load(sys.stdin)['result']['content'][0]['text'])
for t in r: print(f'  [{t[\"priority\"]}] {t[\"title\"]}')" 2>/dev/null

echo ""
echo "=== Upcoming Events ==="
call "{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"get_events\",\"arguments\":{\"date_from\":\"$TODAY\",\"limit\":5}}}" \
  | python3 -c "
import sys, json
r = json.loads(json.load(sys.stdin)['result']['content'][0]['text'])
# NOTE: start_at is a STRING like '2026-04-18T11:30:00+00:00' — parse before date math
for e in r: print(f'  {e[\"start_at\"][:16]} {e[\"title\"]}')" 2>/dev/null

examples/create-task.sh

#!/bin/bash
# Create a task via MCP
TOKEN="${1:?Usage: ./create-task.sh YOUR_TOKEN 'Task title'}"
TITLE="${2:?Usage: ./create-task.sh YOUR_TOKEN 'Task title'}"
PRIORITY="${3:-medium}"

curl -s -X POST "https://api.telldone.app/mcp/user/mcp" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d "{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"create_task\",\"arguments\":{\"title\":\"$TITLE\",\"priority\":\"$PRIORITY\"}}}" \
  | python3 -m json.tool

套餐与访问权限

套餐	MCP 访问权限	读取	写入	价格
Free	--	--	--	$0
Basic	--	--	--	$4.99/mo
Pro	读写	9 个工具	11 个工具	$11.99/mo
Ultra	读写	9 个工具	11 个工具	$24.99/mo

Pro 和 Ultra 提供相同的 MCP 工具。Ultra 的配额更高（无限笔记，每月 1500 分钟 STT，每天 300 次上传）。

身份验证

TellDone 支持两种连接方式——任选其一。

OAuth 2.1（推荐）

一键通过浏览器登录，无需复制或存储任何内容。符合标准：OAuth 2.1 搭配 PKCE（S256）、授权服务器与受保护资源发现（RFC 8414 / RFC 9728）、受众绑定访问令牌（RFC 8707）、轮换刷新令牌，以及客户端 ID 元数据文档（因此 Claude Desktop / claude.ai 无需手动注册即可连接）。访问权限采用范围限定：你可以在授权页面准确审批应用可执行的操作，且只读或读写权限取决于你的套餐。你可以随时在设置 → AI Agents中撤销授权，或禁用 MCP。

• 连接器 URL：https://api.telldone.app/mcp/user
• 发现：https://api.telldone.app/.well-known/oauth-protected-resource
• 范围：notes:read · notes:write · tasks:read · tasks:write · events:read · events:write · reports:read · tags:read · tags:write · profile:read · offline_access

Bearer 令牌

适用于不支持 OAuth 的客户端。在 Web 应用中生成长期有效的令牌——设置 → AI Agents (MCP) → 启用——并通过 Authorization: Bearer <token> 发送。

• 端点 URL：https://api.telldone.app/mcp/user/mcp
• 重新生成：设置 → AI Agents → 重新生成（旧令牌将立即撤销）
• 禁用：设置 → AI Agents → 禁用（令牌将被删除）

**速率限制（两种方式均适用）：**每秒 5 个请求。

传输

MCP Streamable HTTP（无状态）。每个请求相互独立。

POST https://api.telldone.app/mcp/user/mcp
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

链接

• 应用：app.telldone.app
• 网站：telldone.app
• 文档：docs.telldone.app
• iOS 应用：App Store