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

Security Scan

The skill's instructions, files, and requirements are coherent with a Notion MCP client that delegates OAuth and network calls to an existing 'uxc' CLI; nothing requested or installed is disproportionate to that purpose.

Purpose & Capability

Name/description describe Notion MCP operations and the skill only requires use of the 'uxc' CLI and network access to mcp.notion.com/mcp; these are expected for the stated functionality and no unrelated credentials or services are requested.

Instruction Scope

SKILL.md limits runtime actions to discovery, OAuth via uxc, reading/fetching/searching, and guarded write flows with explicit user confirmation; it instructs the agent to ask the user to paste the OAuth callback URL (contains auth code/state), which is appropriate for an interactive OAuth flow and is explicitly constrained (do not ask for bearer tokens).

Install Mechanism

This is instruction-only with no install spec. The skill assumes 'uxc' is already installed in PATH; no downloads or archive extraction are performed by the skill itself.

Credentials

No environment variables, credentials, or config paths are required by the skill. OAuth is handled by 'uxc' and the skill does not request unrelated secrets or broad system access.

Persistence & Privilege

Skill does not request always:true, does not modify other skills' configurations, and contains no persistent installation steps. Autonomous invocation remains enabled by platform default but the skill itself is not forcing persistent presence.

Assessment

This skill appears to do what it says: it relies on your locally installed 'uxc' CLI to perform OAuth and Notion MCP calls and asks you to paste the browser callback URL (which will contain an authorization code). Before installing/use: ensure the 'uxc' binary is from a trusted source, verify network calls target mcp.notion.com/mcp, and be prepared to confirm any write operations (the skill requires explicit confirmation). The callback URL you paste contains an auth code — that's expected for the OAuth flow; do not paste raw bearer tokens or secrets into chat. If you want to avoid any automated actions, keep autonomous agent invocation disabled or confirm prompts before allowing writes.

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