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.

4installs

Sourceholon-run/uxc

Added on2026-04-24

NPX Install

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

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.

Ensure endpoint mapping exists:

uxc auth binding match mcp.notion.com/mcp

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

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

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.

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

.

Prefer read path first:
- Search/fetch current state before any write.
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:

Start login command and wait for authorization URL output.
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.

Run

uxc auth oauth complete notion-mcp --session-id <session_id> --authorization-response '<callback-url>'

.

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