Better Notion MCP

mcp-name: io.github.n24q02m/better-notion-mcp

Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call.

Table of contents

• Features
• Install
• CLI
• Remote (HTTP mode)
• Smithery
• Status
• Documentation
• Tools
• Configuration
• Deploy to Cloudflare
• Comparison
• Security
• Build from Source
• Trust Model
• License

Features

• Markdown in, Markdown out -- human-readable content instead of raw JSON blocks
• 8 composite tools, 39 actions -- one call instead of chaining 2+ atomic Notion endpoints (plus config, help, and a relay-setup tool)
• Auto-pagination and bulk operations -- no manual cursor handling or looping
• Tiered token optimization -- ~77% reduction via compressed descriptions + on-demand help tool
• Dual transport -- local stdio (integration token) or remote HTTP (OAuth 2.1, no token to paste)

Install

Run with npx (Node.js >= 24) and a Notion integration token from https://www.notion.so/my-integrations (starts with ntn_):

// MCP client config (e.g. .mcp.json / Claude Code / Cursor)
{
  "mcpServers": {
    "better-notion-mcp": {
      "command": "npx",
      "args": ["--yes", "@n24q02m/better-notion-mcp@latest"],
      "env": { "NOTION_TOKEN": "ntn_your_token_here" }
    }
  }
}

Or run the published Docker image (stdio):

docker run --rm -i -e NOTION_TOKEN=ntn_your_token_here n24q02m/better-notion-mcp:latest

See the Documentation section for per-client setup (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) and HTTP/OAuth mode.

CLI

Installing the package exposes a better-notion-mcp binary (run it with npx or after a global install). It has no subcommands -- running it starts the MCP server and speaks the protocol over stdin/stdout, so it is normally launched by an MCP client rather than by hand.

# Start the stdio server (default transport; requires NOTION_TOKEN)
NOTION_TOKEN=ntn_your_token_here npx --yes @n24q02m/better-notion-mcp@latest

# Start the remote HTTP server (OAuth 2.1) instead of stdio
npx --yes @n24q02m/better-notion-mcp@latest --http

See Configuration for the full environment-variable reference.

Remote (HTTP mode)

Deployed with the HTTP transport, the server is a remote endpoint gated by OAuth 2.1 -- no integration token to paste. Point an MCP client that supports remote HTTP servers at the host you deployed it on:

// MCP client config -- remote HTTP (OAuth 2.1)
{
  "mcpServers": {
    "better-notion-mcp": {
      "type": "http",
      "url": "https://<your-host>/mcp"
    }
  }
}

On first connect the client opens Notion's OAuth consent screen; per-user access tokens are held in-process only (see Trust Model). To stand up such an instance, see Self-Hosting (Remote Mode) and Deploy to Cloudflare.

Smithery

The repo ships a smithery.yaml config for Smithery. Smithery launches the server over stdio (npx -y @n24q02m/better-notion-mcp) and requires no install-time config -- provide your Notion credentials at runtime through the server's own setup flow (NOTION_TOKEN env, or the relay form; see Configuration).

Status

2026-05-02 -- Architecture stabilization update

Past months saw significant churn around credential handling and the daemon-bridge auto-spawn pattern. This caused multi-process races, browser tab spam, and inconsistent setup UX across plugins. The architecture is now stable: 2 clean modes (stdio + HTTP), no daemon-bridge layer, no auto-spawn from stdio.

Apologies for the instability period. If you encountered issues with prior versions, please update to the latest release and follow the current Setup guide -- most prior workarounds are no longer needed.

Related plugins from the same author:

• wet-mcp -- Web search + content extraction
• mnemo-mcp -- Persistent AI memory
• imagine-mcp -- Image/video understanding + generation
• better-email-mcp -- Email management
• better-telegram-mcp -- Telegram
• better-godot-mcp -- Godot Engine
• better-code-review-graph -- Code review knowledge graph

All plugins share the same architecture -- install once, learn pattern transfers.

Documentation