notion

notion 快速入门

让 AI 帮你读写 Notion 不再“403 Forbidden”——这个 Skill 教 3 步搞定 OAuth、Database 查询与 Block 写入。

这是什么?解决什么问题?

notion Skill 来自 Anthropic 在 anthropics/skills 生态中的整合,基于 Notion 官方 makenotion/notion-mcp-server,通过 Model Context Protocol(MCP)把 Notion API 暴露给 Claude Code / Cursor 等 AI 编程 Agent。 普通开发者想用 AI 操作 Notion 时,通常面临几个坎:

• API 权限难懂:Notion 内部 integration 跟 workspace、page、database 的授权关系很容易配错;
• Database vs Page:Database 有 schema、filter、sort,Page 是 block tree,API 调用方式完全不同;
• Block 类型多到爆炸:paragraph、heading_1/2/3、bulleted_list、code、callout、table、column_list 等等,手写 JSON 痛苦;
• 分页与限制:单次最多 100 条,rich text 每段 2000 字符上限;
• 不能写 Markdown:Notion API 只接受 block JSON,要把 Markdown 转 block 是脏活。 notion Skill 把这套复杂性封装在 MCP 工具后面,Agent 可以用类似自然语言的方式让你“读 / 写 / 查 / 改”Notion。 适合 Notion 重度用户、Knowledge Manager、内容运营、产品经理,以及想把 AI 接进自己知识库的小白。

准备工作

1. Notion 账号 + 一个 workspace(免费版即可,但要能创建 integration)。
2. Notion Integration Token:https://www.notion.so/my-integrations 创建,复制 Internal Integration Secret(形如 secret_xxx)。
3. AI 编程 Agent:Claude Code 体验最完整,Cursor 也可以。
4. Node.js ≥ 18 或 Python ≥ 3.10,本 Skill 同时支持两套 SDK。
5. 在 Notion 中给 integration 授权:在目标页面右上角 “…” → “Connections” → 添加你刚创建的 integration。

3 步快速上手

第 1 步:克隆 Notion MCP Server

git clone https://github.com/makenotion/notion-mcp-server.git
cd notion-mcp-server
npm install
npm run build

或在 Anthropic 官方 Skills 索引中找到 notion 子目录加载提示词。

第 2 步:在 Claude Code 中配置 MCP

编辑 ~/.claude/mcp.json(或项目根 .mcp.json):

{
"mcpServers": {
"notion": {
"command": "node",
"args": ["./notion-mcp-server/build/index.js"],
"env": {
"NOTION_TOKEN": "secret_xxx"
}
}
}
}

重启 Claude Code,执行 /mcp 应能看到 notion 工具已注册。

第 3 步:用 Skill 跑第一个任务

请用 notion Skill 帮我:

1. 列出我 workspace 里所有标题含 “Roadmap” 的页面;

2. 把第一个页面的内容读出来;

3. 在最末尾追加一个 H2 “更新于 2026-06-17” 和一段 paragraph “本周完成 3 件事”。

Agent 会:

1. 调 notion.search 找到目标页面 ID;

2. 调 notion.blocks.children.list 递归读 block tree;

3. 调 notion.blocks.children.append 写入新的 H2 + paragraph blocks。

常见踩坑

1. 403 — object_not_found:Integration 没被加到那个页面/数据库的 “Connections”,Skill 提示 Agent 在写之前先报 “需要先授权 X 页面给 integration”。

2. Database 查询没返回:很多新手忘了 database 也是 page,先 retrieve 拿 data_source_id,再 query.data_source 才是正确顺序,Skill 给出顺序模板。

3. rich text 超 2000 字符:Notion 限制,Skill 提示 Agent 自动按段落切分。

4. 分页 token 没循环:Skill 提示必须 while (results.has_more) { start_cursor = results.next_cursor },否则只拿到 100 条。

5. 修改 Page 标题:pages.update 的 properties.title 因数据库 / 页面类型不同而 schema 不同,Skill 提示 Agent 先 retrieve 再 update。

6. Block children 嵌套深度:Notion 限制 2 级 column 嵌套,Skill 提示拆成多步 append。

初级用法

1. 读一个页面

用 notion Skill 读 https://www.notion.so/xxx-Roadmap 页面的内容并以 Markdown 形式展示给我。

2. 创建新页面

请在 “团队周会” 数据库下新建一个页面:title = “2026-W24 周会”,status = 进行中,owner = 我。

3. 批量改属性

把 “待办” 数据库里所有 status = “todo” 的条目,owner 字段改成 “Alice”,请用 notion Skill。

高级玩法

1. 把 Markdown 文档批量灌入 Notion

# 用 notion-to-md / md-to-notion 桥接

npx md-to-notion --token secret_xxx --parent page_id ./docs

Skill 提示 Agent 帮你分章节上传,自动建 H1/H2 层级。

2. 与 Notion Webhook 联动

第三方服务(Stripe / GitHub / Linear)推事件 → 通过 Zapier / Make 写 Notion → Agent 读 Notion 总结日报。

3. 数据库做 “AI 看板”

让 Agent 每天从 Notion 数据库里拉 “待 review” 条目,跑总结并写回 paragraph block,实现 “AI 助理 24h 在线”。

4. 跨 workspace 迁移

# export → json

npx notion-export notion --token secret_xxx

# 导入到新 workspace

npx notion-import --token new_secret_xxx ./export.json

Skill 提示 Agent 帮你处理 page id 重映射。

小技巧

• API 调用频率限制:Notion 平均 3 req/s,Skill 提示用 p-limit 限流。

• 大文档分块写:一次 append 不要超过 100 个 block,分多次 append。

• database query 用 filter 而不是拉全量在本地筛:省时间省配额。

• 公式字段无法直接写:通过修改前置字段触发计算。

• 善用 archived: true 软删除:Skill 提示查 “已归档” 加 archived: true 过滤。

参考链接

• Anthropic Skills 总仓库:https://github.com/anthropics/skills

• Notion MCP Server:https://github.com/makenotion/notion-mcp-server

• Notion API 官方文档:https://developers.notion.com/reference/intro

• Notion Integration 创建:https://www.notion.so/my-integrations

• notion-to-md:https://github.com/souvikinator/notion-to-md

• md-to-notion:https://github.com/sillsdev/md-to-notion

• Model Context Protocol 规范:https://modelcontextprotocol.io/

• Claude Code MCP 集成:https://docs.claude.com/en/docs/claude-code/mcp