# io.github.ai-aviate/better-notion (npm · better-mcp-notion)

Operate Notion with a single Markdown document — read, create, and update pages in one call.

- Trust score: 62/100 (medium)
- Change this week: +20
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `better-mcp-notion`: 62/100 (this document), [markdown](https://verifymcp.io/servers/ai-aviate-better-notion/better-mcp-notion.md), [page](https://verifymcp.io/servers/ai-aviate-better-notion/better-mcp-notion)

## Channel facts

- Registry: `npm`
- Package: `better-mcp-notion`
- Version: `0.3.2`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 83/100
  - No malware found by supply-chain analysis.
  - CVE check failed: a known medium-severity CVE affects katex 0.12.0, reached via @tryfabric/martian > remark-math > micromark-extension-math > katex. A fixed version is available.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (174 of 178), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 32/100
  - Source repository is publicly reachable at the declared URL.
  - Provenance check failed: no build-provenance attestation is published.
  - License check failed: the license (Elastic-2.0) isn't a recognized OSI-approved license.
  - Actively maintained (last published 164 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 59/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 2282 tokens (~253/item across 9 items; 9 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 27/100
  - Stability observed for 8 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### Claude

```bash
claude mcp add ai-aviate-better-notion -- npx -y better-mcp-notion
```

### Codex

```bash
codex mcp add ai-aviate-better-notion -- npx -y better-mcp-notion
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "ai-aviate-better-notion": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "better-mcp-notion"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add ai-aviate-better-notion --command npx --arg -y --arg better-mcp-notion
```

### Hermes

```yaml
mcp_servers:
  ai-aviate-better-notion:
    command: "npx"
    args: ["-y", "better-mcp-notion"]
```

### Other

```json
{
  "mcpServers": {
    "ai-aviate-better-notion": {
      "command": "npx",
      "args": [
        "-y",
        "better-mcp-notion"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-02 (score 62, +29)

- [security regression] CVE-2024-28246 affects this package: medium
- [security regression] CVE-2024-28245 affects this package: medium
- [security regression] CVE-2025-23207 affects this package: medium
- [security regression] CVE-2024-28243 affects this package: medium
- [security regression] Provenance: unverified → fail
- [security regression] Known CVEs: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [functional regression] License: unverified → fail
- [functional regression] Security disclosure: fail → unverified
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Stability: unverified → 0.23
- [functional improvement] Schema quality: unverified → good
- [functional improvement] Dependency health: unverified → partial
- [functional] Licence: Elastic-2.0

### 2026-08-01 (score 33, +9)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 24, −18)

- [security regression] Malware scan: pass → unverified

### 2026-07-27 (score 42)

First indexed and scored.

## MCP tools (9)

### `read` (~261 tokens)

Read a Notion page and return it as Markdown with YAML frontmatter.

Returns frontmatter fields:
\- id, url: page identifiers
\- title: page title
\- parent / database: parent page ID or database ID
\- icon, cover: emoji or image URL
\- properties: database properties (if the page belongs to a database)
\- created, last_edited: timestamps (read-only)

The body contains the page content as standard Markdown.

The output can be edited and passed directly to the "write" tool to update the page.

Use "depth" to include child pages in a single call (default: 1 = current page only, 2 = include children, 3 = include grandchildren).

Example output:
\---
id: abc123-def456
title: Weekly Review
database: task-db-id
properties:
  Status: In Progress
  Tags:
    - backend
\---
\## Notes
\- Completed API design

Input parameters:

- `depth` (integer): How deep to read child pages: 1 = this page only (default), 2 = include children, 3 = include grandchildren
- `page` (string, required): Notion page URL (https://notion.so/...) or page ID (UUID or 32-char hex)

### `write` (~625 tokens)

Create or update Notion pages from Markdown with YAML frontmatter.

Mode (default "auto"): if frontmatter has "id" → update, otherwise → create.

\## Batch mode
Separate multiple pages with a line containing only "===" to create/update them in one call.

\## Frontmatter fields

\| Field | Create | Update | Description |
\|-------|--------|--------|-------------|
\| id | - | required | Page ID to update |
\| title | recommended | optional | Page title |
\| parent | required* | ignored | Parent page name or ID |
\| database | required* | ignored | Database name or ID (*either parent or database) |
\| icon | optional | optional | Emoji (e.g. 📋) or image URL |
\| cover | optional | optional | Cover image URL |
\| properties | optional | optional | DB properties (see below) |

Properties are auto-matched to the database schema. Use the exact property name as key.
Read-only fields from read output (url, created, last_edited, formula, etc.) are safely ignored.

\## Examples

\### Create a page under a parent page:
\```
\---
title: Meeting Notes
parent: "Project Alpha"
icon: "📝"
\---
\## Agenda
\- Review progress
\```

\### Create a database entry:
\```
\---
title: Fix login bug
database: "Task Board"
properties:
  Status: In Progress
  Tags:
    - backend
    - urgent
  Due Date: "2026-03-01"
\---
\## Description
Login fails when password contains special chars.
\```

\### Update an existing page (edit output from read):
\```
\---
id: abc123-def456
title: Updated Title
properties:
  Status: Done
\---
\## New content
Body replaces all existing blocks.
\```

\### Append to an existing page (add content without rewriting):
Use position: "append" to add content to the end, or "prepend" to add to the beginning.
Only the new content needs to be provided — existing content is preserved.
\```
\---
id: abc123-def456
\---
\## New section added at the end
\```

\### Batch create (multiple pages in one call):
\```
\---
title: Task 1
database: "Task Board"
properties:
  Status: Todo
\---
Task 1 details
\===
\---
title: Task…

Input parameters:

- `markdown` (string, required): Markdown with YAML frontmatter. Separate multiple pages with '===' on its own line. See tool description for format.
- `mode` (string): "auto" (default): create if no id, update if id present. "create": force create. "update": force update (requires id).
- `position` (string): "replace" (default): replace all content. "append": add to end (efficient, no need to send existing content). "prepend": add to beginning. Only affects updates.

### `search` (~180 tokens)

Search the Notion workspace by title keyword. Returns a Markdown list with page/database IDs, titles, and metadata.

Use the returned IDs with other tools: read (to get full content), write (to update), list (to query a database), delete, or move.

Example output:
\# Search results: "MCP" (2 results)
1\. **MCP Design Doc** (📝 page)
   \- ID: `abc123`
   \- Last edited: 2026-02-19
2\. **Task Board** (database)
   \- ID: `def456`

Input parameters:

- `filter` (string): Filter by type: "page", "database", or "all" (default)
- `limit` (integer): Max results (default: 10)
- `query` (string, required): Search keyword (matched against page/database titles)

### `list` (~350 tokens)

List database records as a Markdown table, or list child pages of a page.

For databases: returns a table with properties as columns.
For pages: returns a numbered list of child pages.

You can pass a database/page name (resolved via search) or an ID/URL.

\## Filter syntax (databases only)
Simple expressions matched against DB property names and types:
\- "Status is Done" → select/status equals
\- "Priority = High" → select equals
\- "Tags contains backend" → multi_select contains
\- "Done is true" → checkbox equals
\- "Due Date after 2026-03-01" → date after
\- "Score > 80" → number greater_than
\- "Name contains API" → title/rich_text contains
Multiple filters: separate with " AND " (e.g. "Status is Done AND Priority is High")

\## Sort syntax (databases only)
\- "Due Date ascending" or "Due Date asc"
\- "Created descending" or "Created desc"

\## Example output
\# Task Board (24 items)
\| Name | Status | Due Date |
\|---|---|---|
\| Fix login bug | In Progress | 2026-03-01 |

Input parameters:

- `filter` (string): Filter expression (e.g. "Status is Done", "Priority > 3"). See tool description for syntax.
- `limit` (integer): Max items to return (default: 50)
- `sort` (string): Sort expression (e.g. "Due Date ascending", "Created desc")
- `target` (string, required): Database or page: name (e.g. 'Task Board'), ID, or Notion URL

### `delete` (~56 tokens)

Archive (soft-delete) a Notion page. The page is moved to Trash and can be restored from Notion's UI. This does NOT permanently delete the page.

Input parameters:

- `page` (string, required): Page ID or Notion URL to archive

### `move` (~89 tokens)

Move a Notion page to a different parent page or database. The page keeps its content and properties; only the location changes.

Example: move a page into an "Archive" page, or move a task into a different database.

Input parameters:

- `page` (string, required): Page ID or URL of the page to move
- `to` (string, required): Destination: page name, database name, ID, or URL

### `update` (~263 tokens)

Quickly update page properties without rewriting content. Much simpler than the write tool for property-only changes.

The page content (blocks) is never touched — only properties are updated.

\## Parameters
\- page: Page ID, URL, or name
\- properties: Key-value object of properties to set

\## Examples

Update a single property:
  update({ page: "abc123", properties: { "Status": "Done" } })

Update multiple properties:
  update({ page: "My Task", properties: { "Status": "Done", "Priority": "High", "Due Date": "2026-03-01" } })

Supported value types:
\- Text: "value"
\- Number: 42
\- Checkbox: true / false
\- Date: "2026-03-01"
\- Date range: "2026-03-01 to 2026-03-15"
\- Select/Status: "Option Name"
\- Multi-select: ["tag1", "tag2"]
\- URL: "https://..."

Input parameters:

- `page` (string, required): Page ID, URL, or name
- `properties` (object, required): Properties to update as key-value pairs (e.g. { "Status": "Done", "Priority": "High" })

### `schema` (~336 tokens)

View or modify database schema (columns/properties).

\## Actions

\### "list" (default) — View current schema
  schema({ database: "Task Board" })
  Returns: property names, types, and select/multi_select options.

\### "add" — Add a new property
  schema({ database: "Task Board", action: "add", property: "Priority", type: "select", options: ["Low", "Medium", "High"] })

\### "remove" — Remove a property
  schema({ database: "Task Board", action: "remove", property: "Old Column" })

\### "rename" — Rename a property
  schema({ database: "Task Board", action: "rename", property: "Due", name: "Due Date" })

\## Supported types for add
title, rich_text, number, select, multi_select, date, checkbox, url, email, phone_number, status, people, files

For select/multi_select, you can provide initial options.

Input parameters:

- `action` (string): "list" (default): show schema. "add": add property. "remove": remove property. "rename": rename property.
- `database` (string, required): Database name, ID, or URL
- `name` (string): New name for rename action
- `options` (array): Options for select/multi_select (e.g. ['Low', 'Medium', 'High'])
- `property` (string): Property name (required for add/remove/rename)
- `type` (string): Property type for add (e.g. select, number, rich_text)

### `comment` (~122 tokens)

Add or read comments on a Notion page.

\## Read comments
  comment({ page: "abc123" })
  Returns all comments on the page as a Markdown list.

\## Add a comment
  comment({ page: "abc123", body: "Looks good! Ready to ship." })
  Adds a comment to the page.

You can use the page name, ID, or URL.

Input parameters:

- `body` (string): Comment text to add. If omitted, existing comments are returned instead.
- `page` (string, required): Page ID, URL, or name

## Diagnostics

Captured diagnostic sections: Provenance, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/ai-aviate-better-notion/better-mcp-notion#diagnostics

## Score history

- 2026-08-03: 62
- 2026-08-02: 62
- 2026-08-01: 33
- 2026-07-31: 24
- 2026-07-29: 42
- 2026-07-28: 42
- 2026-07-27: 42

## Links

- npm package: https://www.npmjs.com/package/better-mcp-notion
- Socket report: https://socket.dev/npm/package/better-mcp-notion
- Repository: https://github.com/ai-aviate/better-mcp-notion
- Changelog RSS feed: https://verifymcp.io/servers/ai-aviate-better-notion/better-mcp-notion/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/ai-aviate-better-notion/better-mcp-notion/changelog.json
- HTML version of this page: https://verifymcp.io/servers/ai-aviate-better-notion/better-mcp-notion