Back to Details

notion-mcp-skill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Notion MCP Skill

Notion MCP 技能

Use this skill to run Notion MCP operations through 
uxc
with OAuth and guarded write behavior.
Reuse the 
uxc
skill guidance for discovery, schema inspection, OAuth lifecycle, and error recovery. Do not assume another skill is auto-triggered in every runtime. Keep this skill executable on its own.
使用此技能通过
uxc
结合OAuth和受保护的写入行为来执行Notion MCP操作。
复用
uxc
技能的发现、架构检查、OAuth生命周期以及错误恢复相关指引。 不要假设在每个运行时都会自动触发其他技能，确保此技能可独立执行。

Prerequisites

前提条件

  • uxc
    is installed and available in 
    PATH
    .
  • Network access to 
    https://mcp.notion.com/mcp
    .
  • OAuth callback listener is reachable (default examples use 
    http://127.0.0.1:8788/callback
    ).
  • uxc
    skill is available for generic discovery/describe/execute patterns.
  • 已安装
    uxc
    且其路径已添加至
    PATH
    环境变量。
  • 可访问网络地址
    https://mcp.notion.com/mcp
    。
  • OAuth回调监听器可被访问（默认示例使用
    http://127.0.0.1:8788/callback
    ）。
  • uxc
    技能可用于通用的发现/描述/执行模式。

Core Workflow (Notion-Specific)

Notion专属核心工作流

Endpoint argument style in this skill:
  • Prefer shorthand 
    mcp.notion.com/mcp
    (scheme omitted).
  • Full URL 
    https://mcp.notion.com/mcp
    is also valid.
  1. Ensure endpoint mapping exists: 
    • uxc auth binding match mcp.notion.com/mcp
  2. If mapping/auth is not ready, start OAuth login: 
    • uxc auth oauth start notion-mcp --endpoint mcp.notion.com/mcp --redirect-uri http://127.0.0.1:8788/callback --scope read --scope write
    • Prompt user to open the printed authorization URL.
    • Ask user to paste the full callback URL after consent.
    • Complete login with 
      uxc auth oauth complete notion-mcp --session-id <session_id> --authorization-response '<callback-url>'
  3. Bind endpoint to the credential: 
    • uxc auth binding add --id notion-mcp --host mcp.notion.com --path-prefix /mcp --scheme https --credential notion-mcp --priority 100
  4. Use fixed link command by default: 
    • command -v notion-mcp-cli
    • If missing, create it: 
      uxc link notion-mcp-cli mcp.notion.com/mcp
    • notion-mcp-cli -h
    • If command conflict is detected and cannot be safely reused, stop and ask skill maintainers to pick a different fixed command name.
  5. Discover tools and inspect schema before execution: 
    • notion-mcp-cli -h
    • notion-mcp-cli notion-fetch -h
    • notion-fetch
      requires 
      id
      (URL or UUID). Examples: 
      • notion-mcp-cli notion-fetch id="https://notion.so/your-page-url"
      • notion-mcp-cli notion-fetch id="12345678-90ab-cdef-1234-567890abcdef"
    • Common operations include 
      notion-search
      , 
      notion-fetch
      , and 
      notion-update-page
      .
  6. Prefer read path first:
    • Search/fetch current state before any write.
  7. Execute writes only after explicit user confirmation:
    • For 
      notion-update-page
      operations that may delete content, always confirm intent first.
此技能中的端点参数格式：
  • 优先使用简写形式
    mcp.notion.com/mcp
    （省略协议）。
  • 完整URL 
    https://mcp.notion.com/mcp
    同样有效。
  1. 确保端点映射已存在： 
    • uxc auth binding match mcp.notion.com/mcp
  2. 如果映射/认证未就绪，启动OAuth登录： 
    • uxc auth oauth start notion-mcp --endpoint mcp.notion.com/mcp --redirect-uri http://127.0.0.1:8788/callback --scope read --scope write
    • 提示用户打开输出的授权URL。
    • 请用户在同意授权后粘贴完整的回调URL。
    • 执行命令完成登录：
      uxc auth oauth complete notion-mcp --session-id <session_id> --authorization-response '<callback-url>'
  3. 将端点与凭据绑定： 
    • uxc auth binding add --id notion-mcp --host mcp.notion.com --path-prefix /mcp --scheme https --credential notion-mcp --priority 100
  4. 默认使用固定链接命令： 
    • command -v notion-mcp-cli
    • 如果命令不存在，创建链接：
      uxc link notion-mcp-cli mcp.notion.com/mcp
    • notion-mcp-cli -h
    • 如果检测到命令冲突且无法安全复用，请停止操作并请求技能维护者选择其他固定命令名称。
  5. 执行操作前先发现工具并检查架构： 
    • notion-mcp-cli -h
    • notion-mcp-cli notion-fetch -h
    • notion-fetch
      需要
      id
      （URL或UUID）。示例： 
      • notion-mcp-cli notion-fetch id="https://notion.so/your-page-url"
      • notion-mcp-cli notion-fetch id="12345678-90ab-cdef-1234-567890abcdef"
    • 常见操作包括
      notion-search
      、
      notion-fetch
      和
      notion-update-page
      。
  6. 优先执行读取操作：
    • 在执行任何写入操作前，先搜索/获取当前状态。
  7. 仅在用户明确确认后执行写入操作：
    • 对于可能删除内容的
      notion-update-page
      操作，务必先确认用户意图。

OAuth Interaction Template

OAuth交互模板

Use this exact operator-facing flow:
  1. Start login command and wait for authorization URL output.
  2. Tell user:
    • Open this URL in browser and approve Notion access.
    • Copy the full callback URL from browser address bar.
    • Paste the callback URL back in chat.
  3. Run 
    uxc auth oauth complete notion-mcp --session-id <session_id> --authorization-response '<callback-url>'
    .
  4. Optionally confirm success with: 
    • uxc auth oauth info <credential_id>
Do not ask user to manually extract or copy bearer tokens. Token exchange is handled by 
uxc
. Use 
uxc auth oauth login ... --flow authorization_code
only for a single-process interactive fallback.
使用以下面向操作员的标准流程：
  1. 启动登录命令并等待授权URL输出。
  2. 告知用户：
    • 在浏览器中打开此URL并批准Notion访问权限。
    • 从浏览器地址栏复制完整的回调URL。
    • 将回调URL粘贴回聊天窗口。
  3. 执行命令：
    uxc auth oauth complete notion-mcp --session-id <session_id> --authorization-response '<callback-url>'
    。
  4. 可选择通过以下命令确认登录成功： 
    • uxc auth oauth info <credential_id>
不要要求用户手动提取或复制Bearer令牌，令牌交换由
uxc
处理。 仅在单进程交互式回退场景下使用
uxc auth oauth login ... --flow authorization_code
。

Guardrails

防护规则

  • Keep automation on JSON output envelope; do not use 
    --text
    .
  • Parse stable fields first: 
    ok
    , 
    kind
    , 
    protocol
    , 
    data
    , 
    error
    .
  • Use 
    notion-mcp-cli
    as the default command path for all Notion MCP calls in this skill.
  • notion-mcp-cli <operation> ...
    is equivalent to 
    uxc mcp.notion.com/mcp <operation> ...
    .
  • Use direct 
    uxc mcp.notion.com/mcp ...
    only as a temporary fallback when link setup is unavailable.
  • Call 
    notion-fetch
    before 
    notion-create-pages
    or 
    notion-update-page
    when targeting database-backed content to obtain exact schema/property names.
  • Treat operations as high impact by default:
    • Require explicit user confirmation before create/update/move/delete-style actions.
  • If OAuth/auth fails, use 
    uxc
    skill OAuth/error playbooks first, then apply Notion-specific checks in this skill's references.
  • 自动化操作仅使用JSON输出信封，不要使用
    --text
    参数。
  • 优先解析稳定字段：
    ok
    、
    kind
    、
    protocol
    、
    data
    、
    error
    。
  • 在本技能中，所有Notion MCP调用默认使用
    notion-mcp-cli
    作为命令路径。
  • notion-mcp-cli <operation> ...
    等价于
    uxc mcp.notion.com/mcp <operation> ...
    。
  • 仅当链接设置不可用时，才临时使用直接命令
    uxc mcp.notion.com/mcp ...
    作为回退方案。
  • 当操作数据库关联内容时，在执行
    notion-create-pages
    或
    notion-update-page
    前调用
    notion-fetch
    以获取精确的架构/属性名称。
  • 默认将操作视为高影响级别：
    • 在执行创建/更新/移动/删除类操作前，需要用户明确确认。
  • 如果OAuth/认证失败，优先使用
    uxc
    技能的OAuth/错误处理手册，然后参考本技能中的Notion专属检查项。

References

参考资料

  • Notion-specific auth notes (thin wrapper over 
    uxc
    skill OAuth guidance): 
    • references/oauth-and-binding.md
  • Invocation patterns by task: 
    • references/usage-patterns.md
  • Notion-specific failure notes (thin wrapper over 
    uxc
    skill error guidance): 
    • references/error-handling.md
  • Notion专属认证说明（基于
    uxc
    技能OAuth指引的轻量封装）： 
    • references/oauth-and-binding.md
  • 按任务分类的调用模式： 
    • references/usage-patterns.md
  • Notion专属故障排查说明（基于
    uxc
    技能错误处理指引的轻量封装）： 
    • references/error-handling.md