Better Notion

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?

Tools

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.gitcd better-mcp-notionnpm 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-def456title: My Pagedatabase: task-db-idproperties:  Status: In Progress  Tags:    - backend---## Notes- Completed API design

Create a page

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

Create a database entry

write({ markdown: `---title: Fix login bugdatabase: "Task Board"properties:  Status: In Progress  Tags:    - backend    - urgent  Due Date: "2026-03-01"---## DescriptionLogin fails when password contains special chars.` })

Update a page (edit the output from read)

write({ markdown: `---id: abc123-def456title: Updated Titleproperties:  Status: Done---## New contentBody 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 sectionThis 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 1database: "Task Board"properties:  Status: Todo---Task 1 details===---title: Task 2database: "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 schemaschema({ database: "Task Board" })
// Add a columnschema({ database: "Task Board", action: "add", property: "Priority", type: "select", options: ["Low", "Medium", "High"] })
// Rename a columnschema({ database: "Task Board", action: "rename", property: "Due", name: "Due Date" })
// Remove a columnschema({ database: "Task Board", action: "remove", property: "Old Column" })

Comments

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

Frontmatter Reference

Write (create/update)

Read (output only)

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

Development

npm run dev          # TypeScript watch modenpm test             # Run testsnpm 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.