Better Notion MCP

What is Better Notion MCP about?

Better Notion MCP offers a server that translates Notion data into Markdown and bundles common operations into high‑level tools. It replaces the raw JSON‑centric official MCP with a more human‑readable, AI‑friendly interface, handling pagination, batch processing, and token optimisation automatically.

How to use Better Notion MCP?

Obtain a Notion integration token from the Notion developer portal and share the required pages/databases with the integration.
Start the server using the recommended npx command (or Docker as an alternative).
Configure the MCP client to point to the server and invoke tools such as pages.create, databases.query, or content_convert.markdown-to-blocks.
Use the built‑in help tool to retrieve full documentation for any tool when needed.

Quick `npx` configuration

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "@n24q02m/better-notion-mcp@latest"],
      "env": { "NOTION_TOKEN": "<YOUR_NOTION_TOKEN>" }
    }
  }
}

Key features of Better Notion MCP

Markdown‑first content – all page content is served as Markdown rather than raw block JSON.
Composite tools – 9 high‑level tools expose 39 actions, collapsing multiple API calls into a single request.
Auto‑pagination – results are streamed automatically; no manual cursor handling.
Native batch support – bulk operations are performed in a single call.
Token reduction – ~77 % fewer tokens thanks to tiered description loading.
Help & MCP resources – on‑demand full documentation via help tool or notion://docs/* URIs.
Docker image – official image n24q02m/better-notion-mcp for containerised deployments.

Use cases of Better Notion MCP

AI agents that need to read, edit, or create Notion pages without dealing with complex block structures.
Automated knowledge bases where content is stored in Notion but consumed as plain Markdown by downstream services.
Batch migrations moving large sets of pages or database entries with a single API call.
Chat‑driven assistants that retrieve context from Notion while staying within token limits.
Custom integrations that require fast, concise Notion operations inside serverless or edge environments.

FAQ from Better Notion MCP

Q: Do I need Node.js installed? A: Yes, Node.js 24+ is required when running via npx. Docker users only need Docker.

Q: Which environment variable holds the Notion token? A: Set NOTION_TOKEN to the integration token (ntn_...).

Q: Can I use the server without Docker? A: Absolutely. The recommended method is the npx command shown above.

Q: How do I get detailed tool documentation? A: Call the help tool with the tool name or use the notion://docs/* URIs if the client supports MCP Resources.

Q: Is the project open source? A: Yes, it is released under the MIT license and the source is on GitHub.

Markdown-First MCP Server for Notion - Optimized for AI Agents

Why "Better"?

9 composite tools that consolidate Notion's 28+ REST API endpoints into action-based operations optimized for AI agents.

vs. Official Notion MCP Server

Feature	Better Notion MCP	Official Notion MCP
Content Format	Markdown (human-readable)	Raw JSON blocks
Operations	Composite actions (1 call)	Atomic (2+ calls)
Pagination	Auto-pagination	Manual cursor
Bulk Operations	Native batch support	Loop manually
Tools	9 tools (39 actions)	28+ endpoint tools
Token Efficiency	Optimized	Standard

Quick Start

Get your token: https://www.notion.so/my-integrations → Create integration → Copy token → Share pages

Option 1: npx (Recommended)

{
  "mcpServers": {
    "better-notion": {
      "command": "npx",
      "args": ["-y", "@n24q02m/better-notion-mcp@latest"],
      "env": {
        "NOTION_TOKEN": "ntn_..."                  // required: Notion integration token
      }
    }
  }
}

Option 2: Docker

{
  "mcpServers": {
    "better-notion": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "--name", "mcp-notion",
        "-e", "NOTION_TOKEN",                      // required: pass-through from env below
        "n24q02m/better-notion-mcp:latest"
      ],
      "env": {
        "NOTION_TOKEN": "ntn_..."                  // required: Notion integration token
      }
    }
  }
}

Tools

Tool	Actions
`pages`	create, get, get_property, update, move, archive, restore, duplicate
`databases`	create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database, list_templates
`blocks`	get, children, append, update, delete
`users`	list, get, me, from_workspace
`workspace`	info, search
`comments`	list, get, create
`content_convert`	markdown-to-blocks, blocks-to-markdown
`file_uploads`	create, send, complete, retrieve, list
`help`	Get full documentation for any tool

Token Optimization

~77% token reduction via tiered descriptions:

Tier	Purpose	When
Tier 1	Compressed descriptions	Always loaded
Tier 2	Full docs via `help` tool	On-demand
Tier 3	MCP Resources	Supported clients

{"name": "help", "tool_name": "pages"}

MCP Resources (Tier 3)

Clients that support MCP Resources can load full tool documentation:

URI	Description
`notion://docs/pages`	Pages tool docs
`notion://docs/databases`	Databases tool docs
`notion://docs/blocks`	Blocks tool docs
`notion://docs/users`	Users tool docs
`notion://docs/workspace`	Workspace tool docs
`notion://docs/comments`	Comments tool docs
`notion://docs/content_convert`	Content Convert tool docs
`notion://docs/file_uploads`	File Uploads tool docs

Build from Source

git clone https://github.com/n24q02m/better-notion-mcp
cd better-notion-mcp
mise run setup
pnpm build

Requirements: Node.js 24+, pnpm

Contributing

See CONTRIBUTING.md

License

MIT - See LICENSE

Better Notion MCP