Better Notion

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

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Capabilities & Tool Schemas (9)Self-reported

Inspect callable tools, capabilities, and parameters exposed to AI agents by Better Notion.

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.

Documentation Overview

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

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

Go to notion.so/profile/integrations and create a new integration
Copy the API key (ntn_...)
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

Terminal

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

Then set the environment variable:

server.ts

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):

config.json

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

From source

bash

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

Code

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

Returns:

markdown

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

Create a page

Code

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

Create a database entry

Code

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)

Code

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.

Code

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 ===:

Code

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

Code

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

Code

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:

Code

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

Manage database schema

Code

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

Code

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

Terminal

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.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Workplace & Productivity View all alternatives

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars

Stargazers on the source repository.

Last commit

7mo ago

Most recent push to the default branch.

Tools exposed

Callable tools this server registers over MCP.

Directory activity

2 views

Config copies, upvotes, and views on AllMCPs.

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Better Notion

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "better-notion": { "command": "npx", "args": ["-y","better-mcp-notion"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/better-notion?style=directory)](https://allmcps.com/mcp/better-notion)

HTML Embed

<a href="https://allmcps.com/mcp/better-notion"><img src="https://allmcps.com/api/badge/better-notion?style=directory" alt="Better Notion on AllMCPs" /></a>

Technical Specs & Signals

CategoryWorkplace & Productivity

11/14 checks healthy over the last 45d

48Quality signal: Fair · 48/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools25/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 4d ago via OSV.dev · better-mcp-notion (npm)

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🏢 Workplace & Productivity →Best MCP servers for Workplace & Productivity →Best Notion MCP servers →Alternatives to Better Notion →Install in Claude Desktop Install in Cursor Install in VS Code Setup guides for all 13 MCP clients

Better Notion

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

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Not yet automatically verified

We haven't yet run this listing's install command through our automated sandbox check. This isn't a red flag — we're steadily working through the catalog.

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Capabilities & Tool Schemas (9)Self-reported

Inspect callable tools, capabilities, and parameters exposed to AI agents by Better Notion.

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.

Documentation Overview

better-mcp-notion

Japanese / 日本語

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

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

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

Go to notion.so/profile/integrations and create a new integration
Copy the API key (ntn_...)
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

Terminal

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

Then set the environment variable:

server.ts

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):

config.json

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

From source

bash

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

Code

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

Returns:

markdown

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

Create a page

Code

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

Create a database entry

Code

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)

Code

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.

Code

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 ===:

Code

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

Code

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

Code

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:

Code

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

Manage database schema

Code

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

Code

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

Terminal

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.

Read the full README →View source on GitHub →

Related MCP Servers

View all in Workplace & Productivity View all alternatives

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars

Stargazers on the source repository.

Last commit

7mo ago

Most recent push to the default branch.

Tools exposed

Callable tools this server registers over MCP.

Directory activity

2 views

Config copies, upvotes, and views on AllMCPs.

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Better Notion

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "better-notion": { "command": "npx", "args": ["-y","better-mcp-notion"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/better-notion?style=directory)](https://allmcps.com/mcp/better-notion)

HTML Embed

<a href="https://allmcps.com/mcp/better-notion"><img src="https://allmcps.com/api/badge/better-notion?style=directory" alt="Better Notion on AllMCPs" /></a>

Technical Specs & Signals

CategoryWorkplace & Productivity

11/14 checks healthy over the last 45d

48Quality signal: Fair · 48/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership10/20

Documentation & tools25/30

Adoption & activity1/15

Community engagement0/10

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 4d ago via OSV.dev · better-mcp-notion (npm)

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.