# MCP Notion

> Operates a Notion workspace through the official Notion MCP over Code Mode, filling its API gaps with direct Notion API calls.

- Skill: `michelkerkmeester/mcp-notion` (Agent Skill, multi-file: 85 files)
- Install (CLI): `npx get-skill add michelkerkmeester/mcp-notion`
- Raw SKILL.md: https://api.skillmd.com/api/skills/michelkerkmeester/mcp-notion/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: MichelKerkmeester (https://skillmd.com/u/michelkerkmeester)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/michelkerkmeester/mcp-notion

---


<!-- keywords: notion, notion mcp, notion api, notion database, notion data source, notion page, notion property, notion relation, notion rollup, notion formula, notion token, ntn_, notion-mcp-server, notion markdown, notion search -->

# mcp-notion Skill

Notion workspace operations via the **official Notion MCP** (`@notionhq/notion-mcp-server`, 24 tools) over Code Mode, plus **direct Notion API calls** for the five capabilities the MCP does not expose. It knows Notion's data model at the schema layer — data sources, 22 property types, relations, rollups, Formulas 2.0 — so an agent can create, query, and extend a workspace without guessing.

---

## 1. MARKDOWN + DATA-SOURCE CONTRACT: READ BEFORE ANY NOTION WRITE

Two shape rules cause most Notion write failures:

1. **Page bodies vs page properties are different surfaces.** A page's *content* is a tree of **blocks** (append/update via block tools, or the markdown round-trip tools). A page's *metadata* is **properties** typed by its parent data source's schema. Writing prose into a property, or a property value into a block, fails or silently truncates.
2. **API 2.0 replaced "databases" with "data sources"** (API version `2025-09-03`). A database is now a container of one or more **data sources**; queries, schema, relations, and rollups all target a **data source id**, not a database id. Using a database id where a data-source id is required is the most common 400.

Markdown round-trip tools (`retrieve-page-markdown` / `update-page-markdown`) require API version `2026-03-11` and are the token-efficient path for AI. Full detail: `references/database-model.md` and `references/mcp-tools.md`.

**Failure symptom:** a `validation_error` naming `data_source_id`, or property writes that vanish, means a database id was used where a data-source id was required, or content was routed to the wrong surface.

---

## 2. WHEN TO USE

### Activation Triggers (explicit user phrases)

- "notion", "notion mcp", "notion api", "mcp-notion"
- "notion page", "notion database", "notion data source", "query notion"
- "create a notion page", "add a row", "notion property", "notion relation", "notion rollup", "notion formula"
- "notion token", "notion integration", "ntn_", "notion search"
- "upload a file to notion", "notion view", "notion async task"

### Automatic Triggers (keyword patterns)

- `notion` + any action verb (create, read, update, query, search, append, archive)
- "data source" / "property" / "rollup" / "relation" in a Notion context
- MCP tool names: `create-a-page`, `query-data-source`, `retrieve-a-page` (namespaced `notion.notion_<name>`)

### When NOT to Use

- **Community Notion MCP servers** (suekou/mcp-notion-server, awkoy/notion-mcp-server) — this mode uses the **official** `@notionhq/notion-mcp-server` only.
- **Notion→Obsidian migration mechanics (running the importer itself)** — the importer runs inside the Obsidian desktop app, not here; this mode is the read-side inventory enabler (`references/migration-inventory.md`), not the importer.
- Generic markdown authoring with no Notion workspace — use `@markdown` / `sk-doc`.
- Non-Notion knowledge apps (Obsidian, ClickUp docs) — wrong surface (`mcp-obsidian`, `mcp-click-up`).

---

## 3. SMART ROUTING

The `mcp-tooling` hub routes a Notion request here when the prompt names Notion or one of its surfaces (a page, a database or data source, a property, a relation, a token) and the hub's `mcp-notion` signal selects this packet.
The router makes two decisions: the official 24-tool MCP carries page, block, data-source, comment, user and search work while direct Notion API calls fill the five gaps, and the backend is the headless local stdio server, with the remote OAuth server only for an interactive session.

`references/mcp-tools.md` is the default reference and the fallback suggestion, `references/database-model.md` and `references/property-types.md` load for schema intent, `references/api-gap-tools.md` for a gap, `references/troubleshooting.md` for install or an error, and `references/migration-inventory.md` for a migration inventory.

A request that scores no intent returns `UNKNOWN_FALLBACK` with its disambiguation checklist, never a silent default.
Read [`ROUTER.md`](./ROUTER.md) before selecting skill-local resources; open only the matched files.

---

## 4. HOW IT WORKS

### Backend Comparison

| Dimension | Local stdio (default, headless) | Remote MCP (interactive) |
|---|---|---|
| **Transport** | stdio via `npx -y @notionhq/notion-mcp-server` | Streamable HTTP at `https://mcp.notion.com/mcp` |
| **Auth** | `NOTION_TOKEN` (`ntn_…` internal-integration token) | OAuth (browser) |
| **Headless?** | **Yes** — the only Code-Mode-capable backend | No — interactive only |
| **Tool names** | `create-a-page`, `retrieve-a-page`, … | `notion-create-pages`, … + async tasks |
| **Status** | **Deprecated** by Notion, still functional | **Recommended** by Notion |
| **Used by** | Code Mode / automation | Human-in-the-loop clients |

> **Deprecation note.** Notion is deprecating the open-source local server in favor of the remote OAuth server. Code Mode is headless, so the local stdio server is the correct (and only) choice here today; `references/troubleshooting.md` carries the local→remote migration path for when the operator moves to an interactive workflow.

### Official Notion MCP — via Code Mode (default path)

The registered `notion` manual launches `@notionhq/notion-mcp-server` over **stdio** with `npx -y`. It talks to Notion's REST API with the integration's `NOTION_TOKEN`.

**Prerequisites:**
- Code Mode MCP configured, with the `notion` manual in `.utcp_config.json` (already registered — see INSTALL-GUIDE).
- `notion_NOTION_TOKEN` (an `ntn_…` internal-integration token) available to Code Mode, and the integration granted content access to the target pages/data sources.

**Configuration** (`.utcp_config.json`, `manual_call_templates`) — already applied:
```json
{
  "name": "notion",
  "call_template_type": "mcp",
  "config": {
    "mcpServers": {
      "notion": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "@notionhq/notion-mcp-server"],
        "env": { "NOTION_TOKEN": "${notion_NOTION_TOKEN}" }
      }
    }
  }
}
```

The `notion_` env prefix matches the manual name `notion`, so `${notion_NOTION_TOKEN}` resolves. This mode documents that registration; it does not rewrite config files.

**Tools:** the server exposes **24 `notion_*` tools** across 6 domains — pages (7), blocks (5), data sources (6), comments (2), users (3), search (1). Confirm every name with `tool_info()` / `list_tools()` before calling; the full catalog with per-tool inputs is in `references/mcp-tools.md`.

**Invocation via Code Mode** (`call_tool_chain` takes a single `code` string):
```typescript
// Code Mode namespaces each tool as notion.notion_<tool_name>. Notion tool names are
// HYPHENATED (create-a-page, retrieve-a-page), so notion.notion_retrieve-a-page is invalid
// JS (it parses as subtraction) — use hyphen-safe BRACKET access. VERIFY once the manual is
// registered: run list_tools() to read the exact callable; Code Mode MAY instead sanitize
// hyphens to underscores (notion.notion_retrieve_a_page). Bracket form is the safe default.
const result = await call_tool_chain({
  code: `
    const hit  = await notion["notion_search"]({ query: "Roadmap" });
    const page = await notion["notion_retrieve-a-page"]({ page_id: hit.results[0].id });
    return page;
  `,
});
```

### The Five API Gaps (direct API)

File uploads, views, non-truncated page property items, and async-task polling exist in the Notion REST API but **not** in the MCP tool surface; daily notes are a convention with no endpoint. Fill them with direct calls (`Authorization: Bearer $notion_NOTION_TOKEN`, `Notion-Version: 2025-09-03`, or `2026-03-11` for markdown/async). Recipes: `references/api-gap-tools.md`.

**When to prefer the remote MCP:** interactive sessions where OAuth is available and async-task tools are needed. Otherwise stay on the local stdio backend.

**Limitations:** search is title-only (no full-text content search); pages archive rather than hard-delete; the workspace is cloud-only (no headless filesystem); rate limit ≈ 3 req/s per integration with `Retry-After`.

---

## 5. RULES

### ✅ ALWAYS

1. **Resolve the backend before acting** — Code Mode uses the local stdio backend with `NOTION_TOKEN`; only route to the remote OAuth backend when an interactive session is genuinely available. Probe, do not assume.
2. **Target a data-source id, not a database id** — API 2.0 made data sources the primary abstraction; queries, schema, relations, and rollups all take a `data_source_id`.
3. **Route content to the right surface** — page prose → blocks (or markdown round-trip tools); metadata → typed properties. Never cross them.
4. **Confirm MCP tool names with `list_tools()` / `tool_info()`** before calling — Notion tool names are hyphenated (`create-a-page`), so the hyphen-safe callable is bracket-access `notion["notion_create-a-page"]` unless `list_tools()` shows Code Mode sanitized them to underscores.
5. **Read a data source's schema before writing rows** — property types and select options are schema-defined; writing an undefined option or wrong-typed value fails.
6. **Handle the rate limit** — ≈3 req/s per integration; on `429` back off with jitter and honor `Retry-After`. Batch reads where possible.
7. **Pin the API version per operation** — `2025-09-03` for most tools, `2026-03-11` for markdown round-trip and async tasks.
8. **Preview destructive ops** — confirm the exact page/row before archive; Notion archives (recoverable) rather than hard-deletes, but bulk archives are still disruptive.

### ⛔ NEVER

1. **Never hardcode the token** — read it from `notion_NOTION_TOKEN` in the Code Mode environment; never inline `ntn_…` in a command, note, or example.
2. **Never use a community Notion MCP server as the default** — this mode is the official `@notionhq/notion-mcp-server`.
3. **Never assume the remote OAuth backend works headless** — it cannot; Code Mode must use the local stdio backend.
4. **Never auto-modify `.utcp_config.json`, `.env.example`, `opencode.json`, or hub files** — the `notion` manual is already registered there; if it needs changing, print the config for the user and never write these files programmatically.
5. **Never fabricate pages, rows, or property values** — if a query returns empty, the data source is genuinely empty or the integration lacks access. Report it.
6. **Never treat search as full-text** — `search` matches titles only; to find by content, retrieve candidate pages and inspect client-side.
7. **Never write markdown into a property field** — prose belongs in blocks or the markdown round-trip; properties are typed values.

### ⚠️ ESCALATE IF

- No `NOTION_TOKEN` and no OAuth session → direct the user to `INSTALL-GUIDE.md` (create an internal integration, copy the `ntn_…` token to `.env`, grant content access).
- A `401`/`403` → the token is missing/wrong, or the integration was not granted access to the target page/data source.
- A `validation_error` naming `data_source_id` → a database id was used where a data-source id is required (2.0 migration); resolve the data source first.
- Persistent `429` → the integration is over ≈3 req/s; reduce concurrency, add backoff, or batch.
- The operator wants an interactive/OAuth workflow → follow the local→remote migration path in `references/troubleshooting.md`.

---

## 6. SUCCESS CRITERIA

- [ ] Code Mode `notion["notion_search"]({query})` returns results (empty is valid) — confirms the manual + token work
- [ ] `list_tools()` shows `notion.notion_*` entries; `tool_info("notion.notion_retrieve-a-page")` resolves a live schema
- [ ] `query-data-source` returns rows for a data-source id the integration can access
- [ ] A page create + markdown round-trip (`update-page-markdown` → `retrieve-page-markdown`) preserves content
- [ ] An API-gap call (e.g. a page-property-item `GET`) returns data with the Bearer token from the environment
- [ ] `bash scripts/doctor.sh` reports Node/npx, the `notion` manual, and `notion_NOTION_TOKEN` state without mutating

---

## 7. INTEGRATION POINTS

**Gate 2 (Skill Routing):** activates at ≥0.8 confidence for Notion workspace requests. The advisor matches on `notion`, `notion mcp`, `notion database`, `notion data source`, `notion page`, `notion token`.

**Code Mode MCP:** the official Notion MCP tools are invoked via `mcp__code_mode__call_tool_chain`; Code Mode namespaces each as `notion.notion_<tool_name>` — use hyphen-safe bracket access since Notion names are hyphenated. See `references/mcp-tools.md`.

**Migration:** this mode is the read-side inventory enabler for Notion→Obsidian migration (`references/migration-inventory.md`) — the same knowledge layer that operates a live workspace reads its structure to drive an Obsidian import; the write-side reconstruction method lives in `mcp-obsidian`'s `references/notion-migration.md`.

**Memory:** save Notion workflow context (target data-source ids, integration name, backend) with `/speckit:save` when switching sessions.

**Tool Usage:** Bash for direct API calls and `scripts/`; `mcp__code_mode__call_tool_chain` for MCP operations; Read to load references on demand.

---

## 8. QUICK REFERENCE

### Notion MCP tool surface (24 tools, 6 domains — confirm names with `tool_info()`)

| Domain | Count | Representative tools |
|---|---|---|
| **Pages** | 7 | create, retrieve, update, archive; markdown retrieve/update |
| **Blocks** | 5 | retrieve, children, append, update, delete |
| **Data sources** | 6 | query, retrieve, update, create, templates |
| **Comments** | 2 | create, list |
| **Users** | 3 | list, retrieve, bot |
| **Search** | 1 | title search |

### The 5 gaps → direct API (`references/api-gap-tools.md`)

| Gap | Endpoint family |
|---|---|
| File uploads | `POST /v1/file_uploads` (+ send / complete) |
| Views | data-source view endpoints |
| Page property items | `GET /v1/pages/{id}/properties/{prop}` |
| Async tasks | task-status endpoint (native on remote MCP) |
| Daily notes | convention (no endpoint) |

### Code Mode call pattern

```typescript
// 24 tools, namespaced notion.notion_<tool_name>; hyphenated names → bracket access.
// Confirm the exact callable with list_tools() before relying on either form.
await call_tool_chain({
  code: `
    const ds = await notion["notion_query-data-source"]({
      data_source_id: "DATA_SOURCE_ID",
      filter: { property: "Status", status: { equals: "In progress" } },
    });
    return ds.results.map(p => p.id);
  `,
});
```

---

## 9. REFERENCES AND RELATED RESOURCES

**Reference Files (load on demand via router):**
- `references/mcp-tools.md` — the 24-tool catalog by domain + Code Mode invocation
- `references/api-gap-tools.md` — direct Notion API for the 5 uncovered capabilities
- `references/property-types.md` — 22 property types: schema, value, filter/sort
- `references/database-model.md` — data-source hierarchy, relations, rollups, Formulas 2.0
- `references/troubleshooting.md` — auth, rate-limit, API-version, deprecation-migration
- `references/migration-inventory.md` — Notion→Obsidian migration read-side inventory method: the 7-step inventory procedure, the 5 API-gap reads it uses, and the read-limit constraints that shape it

Install guide (front door): [INSTALL-GUIDE.md](INSTALL-GUIDE.md) — token setup, Code Mode registration, dual-backend config.

**Scripts:**
- `scripts/install.sh` — prints the Code Mode manual + `notion_NOTION_TOKEN` env key (read-only)
- `scripts/doctor.sh` — diagnoses Node/npx, the manual, and the token

**Embedded Servers:**
- `mcp-servers/notion-mcp/README.md` — official `@notionhq/notion-mcp-server` config notes (stdio, `NOTION_TOKEN`, dual-backend)

**Examples:**
- `examples/README.md` — Code Mode Notion workflow examples

**Related Skills:**
- `mcp-click-up` — structural sibling (light workflow mode)
- `mcp-obsidian` — sibling knowledge app; the migration counterpart
- `mcp-code-mode` — Code Mode MCP orchestration (used for Notion MCP invocation)

**External:**
- Official Notion MCP server: [makenotion/notion-mcp-server](https://github.com/makenotion/notion-mcp-server)
- Notion API reference: [developers.notion.com/reference](https://developers.notion.com/reference)

