notion-mcp-skill

Original：🇺🇸 English
Translated
1 scripts

Operate Notion workspace content through Notion MCP using the UXC CLI, including search, fetch, users/teams lookup, page/database creation and updates, and comments. Use when tasks require calling Notion tools over MCP with OAuth (authorization_code + PKCE), especially when safe write controls and JSON-envelope parsing are required.

21installs
Sourceholon-run/uxc
Added on

NPX Install

npx skill4agent add holon-run/uxc notion-mcp-skill

Tags

Translated version includes tags in frontmatter
notion-mcpuxc-clioauth-integrationworkspace-automationcontent-management

SKILL.md Content

View Translation Comparison →

Notion MCP Skill

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.

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.

Core Workflow (Notion-Specific)

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.

OAuth Interaction Template

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.

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.

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