Skip to main content
Glama
better-mcp-notion

better-mcp-notion

by ai-aviate

better-mcp-notion

Japanese / 日本語

An MCP server that lets you operate Notion with a single Markdown document.

Existing Notion MCP servers are thin API wrappers that require multiple round-trips for a single operation. better-mcp-notion uses one Markdown document (YAML frontmatter + body) to read, create, and update pages in a single call.

Why better-mcp-notion?

Traditional Notion MCP

better-mcp-notion

Tools

16-22 tools

9 tools

Create a DB entry

3+ calls (search DB, get schema, create page, append blocks)

1 call

Edit a page

4+ calls (get page, get blocks, delete blocks, append blocks)

1 call (read, edit, write)

Format

Raw JSON blocks

Markdown

Context window

Heavy (tool definitions + JSON)

Light

Related MCP server: cs-ai-notion-mcp

Tools

Tool

Description

read

Read a Notion page as Markdown with frontmatter. Supports recursive child page reading with depth.

write

Create or update pages from Markdown. Supports batch operations and append/prepend.

search

Search the workspace by keyword. Returns a Markdown-formatted list.

list

List database records as a table or child pages as a list. Supports natural language filter & sort.

update

Quick property update without rewriting content. Just pass page + key-value pairs.

schema

View or modify database schema — add, remove, or rename columns.

comment

Add or read comments on a page.

delete

Archive (soft-delete) a page.

move

Move a page to a different parent page or database.

Quick Start

1. Create a Notion Integration

  1. Go to notion.so/profile/integrations and create a new integration

  2. Copy the API key (ntn_...)

  3. Share the pages/databases you want to access with the integration ("Connect to" in the page menu)

2. Add to your MCP client

Claude Code

claude mcp add better-notion -- npx better-mcp-notion

Then set the environment variable:

export NOTION_API_KEY=ntn_your_api_key_here

Claude Desktop / Cursor / Windsurf

Add to your MCP config file (e.g. claude_desktop_config.json, .cursor/mcp.json):

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "better-mcp-notion"],
      "env": {
        "NOTION_API_KEY": "ntn_your_api_key_here"
      }
    }
  }
}

From source

git clone https://github.com/ai-aviate/better-mcp-notion.git
cd better-mcp-notion
npm install && npm run build

Then point your MCP config to node /path/to/better-mcp-notion/build/index.js.

Usage

Read a page

read({ page: "https://notion.so/My-Page-abc123def456" })

Returns:

---
id: abc123-def456
title: My Page
database: task-db-id
properties:
  Status: In Progress
  Tags:
    - backend
---
## Notes
- Completed API design

Create a page

write({ markdown: `
---
title: Meeting Notes
parent: "Project Alpha"
icon: "📝"
---
## Agenda
- Review progress
- Discuss next steps
` })

Create a database entry

write({ markdown: `
---
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 a page (edit the output from read)

write({ markdown: `
---
id: abc123-def456
title: Updated Title
properties:
  Status: Done
---
## New content
Body replaces all existing blocks.
` })

Append content to an existing page

Use position: "append" to add content to the end without rewriting the entire page. Only the new content needs to be provided — existing content is preserved.

write({ markdown: `
---
id: abc123-def456
---
## New section
This is added to the end of the page.
`, position: "append" })

position: "prepend" adds content to the beginning instead.

Batch create (multiple pages in one call)

Separate pages with ===:

write({ markdown: `
---
title: Task 1
database: "Task Board"
properties:
  Status: Todo
---
Task 1 details
===
---
title: Task 2
database: "Task Board"
properties:
  Status: Todo
---
Task 2 details
` })

Query a database with filters

list({
  target: "Task Board",
  filter: "Status is Done AND Priority is High",
  sort: "Due Date ascending"
})

Filter syntax

  • Status is Done / Status = Done - equals

  • Priority != Low - not equals

  • Tags contains backend - multi-select contains

  • Done is true - checkbox

  • Score > 80 - number comparison (>, <, >=, <=)

  • Due Date after 2026-03-01 - date after/before

  • Combine with AND: Status is Done AND Priority is High

Sort syntax

  • Due Date ascending or Due Date asc

  • Created descending or Created desc

Read with child pages

read({ page: "parent-page-id", depth: 2 })

depth: 1 = current page only (default), 2 = include children, 3 = include grandchildren.

Quick property update

Update properties without rewriting content:

update({ page: "My Task", properties: { "Status": "Done", "Priority": "High" } })

Manage database schema

// View schema
schema({ database: "Task Board" })

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

// Rename a column
schema({ database: "Task Board", action: "rename", property: "Due", name: "Due Date" })

// Remove a column
schema({ database: "Task Board", action: "remove", property: "Old Column" })

Comments

// Read comments
comment({ page: "abc123" })

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

Frontmatter Reference

Write (create/update)

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 or image URL

cover

optional

optional

Cover image URL

properties

optional

optional

Database properties (matched against schema)

Read (output only)

Field

Description

id

Page UUID

url

Notion page URL

title

Page title

parent / database

Parent page or database ID

icon, cover

Emoji or image URL

properties

All database properties

created, last_edited

Timestamps (read-only)

Read-only fields (url, created, last_edited, formulas, etc.) are safely ignored when passed to write.

Development

npm run dev          # TypeScript watch mode
npm test             # Run tests
npm run test:watch   # Test watch mode

License

Elastic License 2.0 (ELv2) — Free to use, modify, and distribute. Cannot be offered as a managed/hosted service.

Available Tools

9 tools
commentA

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.

Inputs: page (required), body.

deleteA

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.

Inputs: page (required).

listA

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

Inputs: target (required), sort, limit, filter.

moveA

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.

Inputs: to (required), page (required).

readA

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

Inputs: page (required), depth.

schemaA

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.

Inputs: database (required), name, type, action, +2 more.

updateA

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://..."

Inputs: page (required), properties (required).

writeA

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 2
database: "Task Board"
properties:
  Status: Todo
---
Task 2 details

Inputs: markdown (required), mode, position.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools have clearly distinct roles: read, delete, search, list, move, schema, and comment are well-separated. The main ambiguity is between write and update, since write can also update properties and content, while update is explicitly scoped to property-only changes. The descriptions help clarify the boundary, but an agent could still hesitate when deciding which to use for a property update.

    Naming Consistency5/5

    All tool names are single lowercase words used as imperative commands, which creates a strong, predictable pattern. Write, read, search, list, delete, move, update, schema, and comment are all short and consistent in style. Minor semantic quibbles like 'schema' being a noun do not break the overall consistency.

    Tool Count5/5

    Nine tools is a well-scoped size for a Notion MCP server. Each tool covers a meaningful area of Notion interaction without excessive fragmentation or redundancy. The set feels appropriately balanced for both simple and moderately complex workflows.

    Completeness4/5

    The server covers the core page lifecycle well: create/update via write, property-only updates, read, search, list, move, delete, schema management, and comments. Minor gaps exist, such as no way to create a brand-new database from scratch, no unarchive/restore operation, and no granular block-level editing. These are workable limitations rather than critical dead ends.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables MCP clients such as Claude, Cursor and ChatGPT to read and write in Notion using a single token, covering search, page creation and editing, database queries, comments and file uploads through natural language. It also supports headless use in automation and CI, with batched, idempotent writes and compact context cost.
      5,456 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Connects MCP clients such as Claude, Cursor, VS Code and Codex to Notion with a single token so agents can search, create and edit pages, query databases, manage blocks and comments, and upload or read files in plain language. Designed for unattended agents and CI, it offers batched idempotent writes, markdown round-tripping, rate-limit retries and low context cost.
      5,456 npm
      MIT