/notion-mcp-skill

name: notion-mcp-skill
description: 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.

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`