Better Notion MCP

A Markdown - first Notion MCP server optimized for AI agents. It integrates the Notion API through 7 composite tools, providing a more efficient and readable operating experience.

Note-taking tools Knowledge management and memory #Notion Integration #Markdown Optimization #AI Tool #Efficient Operation .TypeScript

rating : 2 points

downloads : 7.6K

update time : 2025-12-12

Open Site

What is Better Notion MCP?

Better Notion MCP is a Notion integration tool specifically designed for AI assistants. It simplifies Notion's complex API into 7 powerful composite tools, allowing AI assistants to interact with Notion in a more natural and efficient way. Compared with the official Notion MCP, it processes content in Markdown format and provides functions such as automatic pagination, batch operations, and intelligent search, greatly improving the work efficiency of AI assistants.

How to use Better Notion MCP?

Using Better Notion MCP is very simple: 1) Create an integration in Notion and obtain the API token; 2) Add the MCP server configuration to the AI assistant configuration; 3) The AI assistant can then manage Notion content through natural language instructions. It supports quick installation via NPX and containerized deployment with Docker.

Use cases

Suitable for users who need AI assistants to help manage Notion content, including scenarios such as content creators organizing notes, project managers updating task statuses, students managing learning materials, and team collaboration for content synchronization. It is especially suitable for scenarios that require batch operations and automated processing.

Main Features

Markdown-first Processing

All content is processed in human-readable Markdown format, allowing AI assistants to understand and generate content more naturally without dealing with complex JSON structures.

Composite Operation Tools

Integrates more than 28 Notion API endpoints into 7 powerful composite tools. For example, when creating a page, you can add content and properties at the same time without multiple calls.

Automatic Pagination

Automatically manages pagination when dealing with large amounts of data. AI assistants don't need to worry about technical details and can focus on the content itself.

Batch Operations

Natively supports batch creation, update, and deletion operations, processing multiple items at once to improve efficiency.

Intelligent Search

Automatically detects the best match in database queries. AI assistants can search using natural language descriptions.

Token Efficiency Optimization

Optimizes the response format specifically for AI contexts, reducing unnecessary token consumption and improving cost-effectiveness.

Simple Configuration

Only requires a Notion API token for configuration, without the need for a complex OAuth process. You can get started quickly.

Advantages

Composite operations: Complete multiple steps with one instruction, reducing the number of calls from AI assistants.

Markdown format: Content is more readable, and AI assistants can process it more naturally.

Automatic pagination: No need to manually manage pagination for large amounts of data.

Batch processing: Efficiently process multiple items, saving time.

Intelligent search: Find content using natural language descriptions.

Simple configuration: Only requires an API token for quick integration.

Token optimization: Specifically optimized for AI conversation scenarios.

Limitations

Does not support complex block types such as tables, toggle blocks, and callout blocks.

Does not support database embedding, image, and file upload functions.

Does not support sync blocks and template functions.

Only supports H1 - H3 title levels.

Some advanced Notion functions have not been implemented.

How to Use

Get the Notion API Token

Visit the Notion integration page to create a new integration and copy the generated API token.

Choose the Installation Method

Choose the NPX (recommended) or Docker installation method according to your environment.

Configure the AI Assistant

Add Better Notion MCP to the MCP server configuration of the AI assistant.

Share the Page with the Integration

Share the page to be managed in Notion with the integration you created.

Start Using

Now you can manage Notion content through natural language instructions using the AI assistant.

Usage Examples

Create Learning Notes

Let the AI assistant create structured learning notes in Notion, including titles, chapters, and key content.

Batch Update Task Status

Let the AI assistant batch update the status of project tasks to improve project management efficiency.

Organize Meeting Minutes

Let the AI assistant organize the conversation content into structured meeting minutes and save them to Notion.

Search for Related Materials

Let the AI assistant search for relevant materials on a specific topic in Notion.

Frequently Asked Questions

Do I need programming knowledge to use it?

What's the difference between it and the official Notion MCP?

What types of Notion content are supported?

How is data security ensured?

Is it free?

How can I report issues or request new features?

Related Resources

GitHub Repository

Source code, issue tracking, and contribution guidelines.

NPM Package Page

View version history and installation statistics.

Docker Image

Docker container image and tags.

Notion Integration Creation

The official page for creating Notion API tokens.

MCP Protocol Documentation

Understand the technical details of the Model Context Protocol.

Contribution Guidelines

How to participate in project development and improvement.

🚀 Better Notion MCP

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

🚀 Quick Start

Better Notion MCP is a Markdown-first MCP server for Notion, optimized for AI agents. It consolidates Notion's 28+ REST API endpoints into composite operations, providing a more efficient and user - friendly experience.

✨ Features

Why "Better"?

It offers 7 mega action - based tools that optimize Notion's operations for AI agents.

vs. Official Notion MCP Server

Property	Details
Content Format	Better Notion MCP uses Markdown (human - readable), while the official one uses raw JSON blocks (verbose).
Operations	Better Notion MCP supports Composite actions (create page + content + properties in 1 call), while the official requires atomic operations (2+ separate calls).
Pagination	Better Notion MCP has Auto - pagination (transparent), while the official needs manual cursor management.
Bulk Operations	Better Notion MCP has Native batch support (create/update/delete multiple items at once), while the official requires looping through items manually.
Tool Architecture	Better Notion MCP uses 7 mega action - based tools (30+ actions), while the official has 28+ individual endpoint tools.
Database Query	Better Notion MCP offers Smart search (auto - detect best match), while the official requires manual filters + sorts.
Token Efficiency	Better Notion MCP is Optimized for AI context, while the official has standard API responses.
Setup	Better Notion MCP is simple (only NOTION_TOKEN is needed), while the official uses OAuth flow or token.

📦 Installation

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

NPX (Recommended)

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

Docker

{
  "mcpServers": {
    "better-notion": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "NOTION_TOKEN", "n24q02m/better-notion-mcp:latest"],
      "env": {
        "NOTION_TOKEN": "your_token_here"
      }
    }
  }
}

💻 Usage Examples

Tools Overview

There are 7 mega tools with 30+ actions:

Composite Actions: Combine operations (e.g., create page + content + properties in 1 call)
Auto - Pagination: Transparent handling of large datasets
Bulk Operations: Process multiple items efficiently
Smart Search: Auto - detect best matches in database queries

📚 Documentation

Limitations

Supported Block Types (Markdown Conversion):

✅ Headings (H1 - H3), Paragraphs, Lists (bulleted/numbered)
✅ Code blocks, Quotes, Dividers
✅ Inline formatting (bold, italic, code, strikethrough, links)

Unsupported Block Types:

❌ Tables, Toggles, Callouts, Columns
❌ Databases, Embeds, Images, Files
❌ Synced blocks, Templates

Build from Source

This project uses mise for tool version management. If you don't have mise installed, see mise.jdx.dev.

git clone https://github.com/n24q02m/better-notion-mcp
cd better-notion-mcp

mise trust
mise install

pnpm install
pnpm build

uv venv
uv pip install pre-commit
uv run pre-commit install
uv run pre-commit run --all-file

Prerequisites: mise or Node.js 22+ and pnpm.

Available Commands

pnpm dev                    # Run development server with auto-reload
pnpm build                  # Build the project
pnpm test                   # Run tests
pnpm test:watch             # Run tests in watch mode
pnpm test:coverage          # Run tests with coverage report
pnpm check                  # Check formatting, linting & types (Biome + TypeScript)
pnpm check:fix              # Auto-fix formatting and linting issues