Notion 远程 MCP

notion-remote-mcp 通过 mcporter 使用 Notion，后端由官方托管的 MCP 支持，地址为 https://mcp.notion.com/mcp。 凭证设置 OAuth 令牌会在用户通过 Maverick 连接 Notion 账户时自动通过 $env:NOTION_MCP_OAUTH_TOKEN 注入。 永远不要直接要求用户提供令牌。

工作流程 验证服务器是否可达，然后再进行工具调用：mcporter list notion --schema 在假设页面或数据库 ID 之前进行搜索：使用标题关键字搜索来解析 ID。 在写入之前读取 —— 在追加或更新之前获取当前内容。 在进行破坏性更改（删除、存档、覆盖）之前，使用用户确认目标页面/数据库。

关键工具 search —— 全文搜索页面和数据库，按标题或内容。 当用户按名称引用某些内容时，首先使用此工具。 retrieve_page —— 按 ID 获取页面属性。 当您已经有页面 ID 时使用。 retrieve_block_children —— 获取页面的内容块。 在追加或编辑内容之前需要。 append_block_children —— 将新块（段落、标题、待办事项、代码等）添加到页面。 update_page —— 更新页面属性（标题、状态、日期字段等）。 create_page —— 在父页面或数据库中创建新页面。 query_database —— 过滤和排序 Notion 数据库中的行。 需要数据库 ID，过滤和排序可选。 retrieve_database —— 在查询之前获取数据库的模式（属性定义）。 create_database_item —— 将新行插入数据库。 update_block —— 编辑现有块的内容，按 ID。 delete_block —— 归档块。 这是可逆的（Notion 归档，而不是硬删除）。

工具选择指南 用户要求“查找”或“查阅”某些内容 —— 首先使用 search，然后使用 retrieve_page 或 retrieve_block_children。 用户要求“添加”或“写入”页面 —— 使用 retrieve_block_children 确认当前状态，然后使用 append_block_children。 用户要求更新属性（状态、日期、分配人） —— 使用 update_page。 用户要求查询表/数据库 —— 使用 retrieve_database 获取模式，然后使用 query_database。 用户要求在数据库中创建新条目 —— 使用 create_database_item。

操作规则 始终通过搜索将名称解析为 ID，然后再调用 retrieve_page 或 query_database。 永远不要猜测 ID。 在追加块时，匹配现有的块样式（如果页面使用 callouts，则使用 callouts）。 将 delete_block 和页面归档视为高影响 —— 在执行之前与用户确认。 如果搜索返回多个具有相同标题的匹配项，向用户显示列表并要求他们确认哪一个。 Notion API 速率限制：3 个请求/秒。 不要批量进行快速连续调用 —— 在批量操作之间添加简短的暂停。 如果工具调用失败并返回 401，则令牌已过期。 指示用户在 Maverick 设置中重新连接其 Notion 账户。

常见错误 object_not_found —— 页面或块 ID 错误或集成缺乏访问权限。 检查 Notion 中的共享设置。 validation_error —— 属性名称或块类型错误。 使用 retrieve_database 确认属性名称，然后再写入。 rate_limited —— 减慢速度并在 1 秒后重试。