io.github.ai-aviate/better-notion

Official

by ai-aviate · TypeScript

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

Read, create, and update Notion pages using Markdown format.

README.md7 KBView on GitHub

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

bash

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

Then set the environment variable:

bash

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

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

bash

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.

Install

Configuration

Environment variables

NOTION_API_KEYrequiredsecret

Notion API key (starts with ntn_)

claude_desktop_config.json

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": [
        "-y",
        "better-mcp-notion@0.3.2"
      ],
      "env": {
        "NOTION_API_KEY": "<YOUR_NOTION_API_KEY>"
      }
    }
  }
}