notion MCP server

Notion REST API 封装（Node+TS），供 idea-collector 等 skill 读写 Notion 数据库与页面。

工具一览

| 工具 | 类型 | 说明 | |---|---|---| | notion_check_config | 只读诊断 | 校验 NOTION_API_KEY 是否存在，并返回根页面 ID 的配置状态（rootPage）；v0.6 起取代旧的「三个数据库 ID」配置 | | notion_list_databases | 只读 | 列出指定 Notion 页面下的所有数据库（v0.6 新增），供 idea-collector 等 skill 启动时用 AskUserQuestion 让用户单选 | | notion_get_database | 只读 | 读取数据库 schema（字段名/类型/选项/关联目标库），写入前必须先调用，按返回字段名构造 properties；database_id 为必填，由 notion_list_databases 选定 | | notion_query_database | 只读 | 查询数据库下的页面（筛选 / 排序 / 分页）；database_id 为必填 | | notion_search_pages | 只读 | 全局搜索页面（可限定数据库 + 时间窗口） | | notion_get_page | 只读 | 取页面元数据（属性 + URL + 时间戳，不含正文） | | notion_get_block_children | 只读 | 取页面正文块（支持分页） | | notion_create_page | 写入 | 在数据库下创建新页面（属性 + 可选正文块；database_id 必填） | | notion_update_page | 写入（破坏性） | 更新页面属性 / 归档 | | notion_append_blocks | 写入 | 向页面正文追加块（观点演变追加场景） |

所有写入类工具在 content-producer 插件下都挂了 PreToolUse 人工确认闸（参考 plugin/hooks/hooks.json），写入前会再次弹确认。

配置

| 变量 | 必填 | 说明 | |---|---|---| | NOTION_API_KEY | 是 | Internal Integration Token（格式 secret_xxx） | | NOTION_API_VERSION | 否 | 默认 2026-03-11（与 plugin.json 一致）。版本自适应：<2025-09-03 走旧版 database 端点；≥2025-09-03 自动解析 data source 并改用 /v1/data_sources 端点、建页 parent 转 data_source_id；≥2026-03-11 归档参数自动转写为 in_trash | | NOTION_TIMEOUT_MS | 否 | 默认 30000 | | NOTION_ROOT_PAGE_ID | 是 | 根页面 ID（v0.6 起取代旧的 NOTION_*_DB_ID 三个变量）；skill 启动时调用 notion_list_databases 自动列举该页面下的所有数据库，由用户单选一个作为本次操作的 database_id。值取 Notion 页面 URL 末段 32 位字符 |

凭证可在系统环境变量设置，或直接填在 plugin/.claude-plugin/plugin.json 的 mcpServers.notion-library.env（优先级更高）。

迁移指引（v0.5 → v0.6）

v0.6 起移除三个数据库 ID 配置（NOTION_KNOWLEDGE_DB_ID / NOTION_PROJECT_DB_ID / NOTION_MATERIAL_DB_ID），改为单一根页面 ID。迁移步骤：

1. 在 Notion 中找到承载目标数据库的父页面，复制其 URL 末段 32 位字符 → 设为 NOTION_ROOT_PAGE_ID
2. 确认 Integration 已加入该页面的 Connections（页面右上角 ··· → Connections）
3. 删除旧的三个 *_DB_ID 环境变量或 plugin.json 条目
4. 重启 Claude Code / 终端
5. 启动 idea-collector → 启动时会自动列出根页面下的所有数据库 → 用 AskUserQuestion 选择一个 → 全流程复用

破坏性变更： v0.6 不再支持 NOTION_KNOWLEDGE_DB_ID 隐式回退。调用 notion_get_database / notion_query_database 不传 database_id 会抛 config_error，必须先调 notion_list_databases 选定。

获取 Token

1. 访问 https://www.notion.so/my-integrations
2. 点 New integration → 填写 name（如 idea-collector）→ 关联 workspace
3. Capabilities 至少勾 Read content / Update content / Insert content
4. 复制 Internal Integration Token

添加 Integration 到目标页面

这一步容易忘，必做：

1. 打开配置的根页面（NOTION_ROOT_PAGE_ID 对应页面）
2. 右上角 ··· → Connections → 搜索刚才创建的 integration 并添加
3. Integration 一旦加入根页面，整个页面树下的所有子页面 + 数据库都会获得访问权
4. 否则查询/写入会返回 404 object_not_found

跨平台配置方式

Windows

方式一：永久环境变量（推荐）

setx NOTION_API_KEY "secret_xxx"

配置后需重启终端/Claude Code 使其生效。

方式二：当前窗口生效（重启后失效）

set NOTION_API_KEY=secret_xxx

macOS / Linux

方式一：写入配置文件（推荐）

# 编辑 ~/.bashrc 或 ~/.zshrc
export NOTION_API_KEY="secret_xxx"
export NOTION_ROOT_PAGE_ID="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"  # 根页面 ID（v0.6 起取代三个 *_DB_ID）

# 使配置生效
source ~/.bashrc   # 或 source ~/.zshrc

方式二：plugin.json 内联（优先级最高，无需重启 shell）

{
  "mcpServers": {
    "notion-library": {
      "command": "npx",
      "args": ["-y", "@jesonliu/notion-mcp-server"],
      "env": {
        "NOTION_API_KEY": "secret_xxx",
        "NOTION_ROOT_PAGE_ID": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

频率限制

Notion API 限制 每秒 3 次平均请求。server 内部对工具调用做了简单串行节流（200ms 间隔），普通 skill 使用不会触发 429。如遇批量写入，可适当增大 RATE_LIMIT_MS 或调用方自行 sleep。

错误码对照

| Notion code | 中文提示 | |---|---| | unauthorized | Token 无效或过期 → 重新生成 | | restricted_resource | Integration 未加入目标数据库 Connections → 见上文「添加 Integration 到目标数据库」 | | object_not_found | 数据库/页面 ID 错误或 Integration 未加入 Connections | | validation_error | 参数校验失败（属性 schema 不匹配） → 检查字段名/类型 | | rate_limited | 请求频率超限 → 减慢调用或增大 RATE_LIMIT_MS | | service_unavailable | Notion 服务暂时不可用 → 稍后重试 |

本地开发

# 安装依赖
npm install

# 开发模式（tsx watch）
npm run dev

# 编译
npm run build

# 启动编译产物
npm start

# 跑测试
npm test

关联工具/项目

• 上游 skill：plugin/skills/idea-collector/SKILL.md（调用本 server 的主编排）
• 上游 agent：plugin/agents/organize-ideas.md（调用本 server 写 Notion 页面）
• 配置：plugin/.claude-plugin/plugin.json 的 mcpServers.notion-library 块
• 确认闸：plugin/hooks/hooks.json 的 notion_* 工具匹配项

License

MIT