io.github.ai-aviate/better-notion
Operate Notion with a single Markdown document — read, create, and update pages in one call.
Open source Open in the app JSON README (API)
About
Operate Notion with a single Markdown document — read, create, and update pages in one call.
Details
- Kind
- MCP servers
- Topic
- Files & documents
- Publisher
- ai-aviate
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.2
- Stars
- 2
- Last push
- 2026-02-19T13:34:53Z
- Repository state
- ativo
- Language
- TypeScript
- License
- NOASSERTION
- Added
- 2026-08-29 03:02:23
- Updated
- 2026-08-29 03:02:23
- Origin id
io.github.ai-aviate/better-notion
README
# better-mcp-notion
[Japanese / 日本語](./README_ja.md)
**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
1. Go to [notion.so/profile/integrations](https://www.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
```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
```
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
```
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
```bash
npm run dev # TypeScript watch mode
npm test # Run tests
npm run test:watch # Test watch mode
```
## License
[Elastic License 2.0 (ELv2)](./LICENSE) — Free to use, modify, and distribute. Cannot be offered as a managed/hosted service.