better-mcp-notion
Allows interaction with Notion's API, providing tools for reading, writing, searching, listing, updating, deleting, and moving Notion pages and databases using Markdown documents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@better-mcp-notion Create a task in the Task Board database titled 'Fix login bug' with status In Progress"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
better-mcp-notion
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 a Notion page as Markdown with frontmatter. Supports recursive child page reading with |
| Create or update pages from Markdown. Supports batch operations and append/prepend. |
| Search the workspace by keyword. Returns a Markdown-formatted list. |
| List database records as a table or child pages as a list. Supports natural language filter & sort. |
| Quick property update without rewriting content. Just pass page + key-value pairs. |
| View or modify database schema — add, remove, or rename columns. |
| Add or read comments on a page. |
| Archive (soft-delete) a page. |
| 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
claude mcp add better-notion -- npx better-mcp-notionThen set the environment variable:
export NOTION_API_KEY=ntn_your_api_key_hereClaude 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 buildThen 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 designCreate 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- equalsPriority != Low- not equalsTags contains backend- multi-select containsDone is true- checkboxScore > 80- number comparison (>,<,>=,<=)Due Date after 2026-03-01- date after/beforeCombine with
AND:Status is Done AND Priority is High
Sort syntax
Due Date ascendingorDue Date ascCreated descendingorCreated 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 |
| - | required | Page ID to update |
| recommended | optional | Page title |
| required* | ignored | Parent page name or ID |
| required* | ignored | Database name or ID (*either |
| optional | optional | Emoji or image URL |
| optional | optional | Cover image URL |
| optional | optional | Database properties (matched against schema) |
Read (output only)
Field | Description |
| Page UUID |
| Notion page URL |
| Page title |
| Parent page or database ID |
| Emoji or image URL |
| All database properties |
| 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 modeLicense
Elastic License 2.0 (ELv2) — Free to use, modify, and distribute. Cannot be offered as a managed/hosted service.
Available Tools
9 toolscommentA
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.
searchA
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)
MCP Design Doc (📝 page)
ID:
abc123Last edited: 2026-02-19
Task Board (database)
ID:
def456
Inputs: query (required), limit, filter.
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 progressCreate 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 endBatch 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 detailsInputs: markdown (required), mode, position.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Convert PDFs, Office docs, websites and audio into AI-ready Markdown, then search and ask your docs.
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Related MCP Servers
- AlicenseCqualityDmaintenanceEnables natural language interaction with Notion workspace, including search, page/database management, markdown conversion, and productivity shortcuts.27MIT
- AlicenseCqualityCmaintenanceProvides full CRUD capabilities over Notion pages, databases, and content blocks, enabling natural language search, creation, and modification of Notion data.7MIT
- AlicenseNot gradedqualityAmaintenanceEnables 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 npmMIT
- AlicenseNot gradedqualityAmaintenanceConnects 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 npmMIT