better-notion-mcp

Overview

Better Notion MCP is a well-designed MCP server that streamlines interactions with the Notion API through 10 high-level composite tools. It replaces 28+ individual endpoint calls with more intuitive operations, reducing complexity and token usage by approximately 77%. The server supports two transport modes: stdio for local token-based authentication and HTTP for remote OAuth 2.1 authentication without requiring tokens. The project is actively maintained with recent commits and includes comprehensive documentation.

Try asking AI

After installing, here are 5 things you can ask your AI assistant:

• pages

  Create, read, update, and organize pages

  Try:Create a new page titled 'Project Plan'Try:Get the content of page '123abc'Try:Move the page to a new parent location
• databases

  Database CRUD and page management within databases

  Try:Create a new database with columns for tasks and due datesTry:Query for all completed tasksTry:Update a database page with new values
• blocks

  Read and manipulate block content

  Try:Get all blocks in a pageTry:Append a new paragraph blockTry:Update an existing block's content
• users

  List and retrieve user information

  Try:List all users in the workspaceTry:Get details for user 'user123'Try:Get information about the current user
• workspace

  Workspace metadata and cross-workspace search

  Try:Get workspace informationTry:Search across the entire workspace for specific content
• comments

  Page and block comments

  Try:List all comments on a pageTry:Create a new comment on a block
• content_convert

  Convert between Markdown and Notion blocks

  Try:Convert Markdown to Notion blocksTry:Convert Notion blocks to Markdown
• file_uploads

  Upload files to Notion

  Try:Create a file upload sessionTry:Send a file chunk for uploadTry:Complete a file upload
• setup

  Credential setup via browser relay, status check, reset, re-resolve

  Try:Check setup statusTry:Start a new browser-based setupTry:Reset credentials

Comparable tools

Installation

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

npm install -g @n24q02m/better-notion-mcp
better-notion-mcp

docker run -p 8080:8080 -e NOTION_TOKEN=your-token n24q02m/better-notion-mcp:latest

FAQ

What makes this different from the official Notion API?

This server provides composite tools that combine multiple API calls into single, simpler operations, and uses Markdown instead of raw JSON blocks for better readability and token efficiency.

How secure is the OAuth mode?

The OAuth mode uses OAuth 2.1 with PKCE S256, includes rate limiting, session owner binding with IP checks, and can be fully self-hosted with your own credentials.

Compare better-notion-mcp with