# Notion MCP Skill

> 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.

- Skill: `holon-run/notion-mcp-skill` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add holon-run/notion-mcp-skill`
- Raw SKILL.md: https://api.skillmd.com/api/skills/holon-run/notion-mcp-skill/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: holon-run (https://skillmd.com/u/holon-run)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/holon-run/notion-mcp-skill

---


# 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`