n24q02m/better-notion-mcp

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

Markdown-first Notion API server for AI agents -- 10 composite tools replacing 28+ endpoint calls

CI codecov npm Docker License: MIT

TypeScript Node.js Notion semantic-release Renovate

Sister projects from n24q02m (click to expand)

Project	Tagline	Tag
better-code-review-graph	Knowledge graph for token-efficient code reviews -- fixed search, configurabl...	MCP
better-email-mcp	IMAP/SMTP email server for AI agents -- 6 composite tools with multi-account ...	MCP
better-godot-mcp	Composite MCP server for Godot Engine -- 17 mega-tools for AI-assisted game d...	MCP
better-notion-mcp	Markdown-first Notion API server for AI agents -- 10 composite tools replacin...	MCP
better-telegram-mcp	MCP server for Telegram with dual-mode support: Bot API (httpx) for quick bot...	MCP
claude-plugins	Full documentation: mcp.n24q02m.com — unified docs for all 8 servers + the mc...	Marketplace
imagine-mcp	Production-grade MCP server for image and video understanding + generation ac...	MCP
jules-task-archiver	Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a...	Tooling
mcp-core	Unified MCP Streamable HTTP 2025-11-25 transport, OAuth 2.1 Authorization Ser...	MCP
mnemo-mcp	Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi...	MCP
qwen3-embed	Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF	Library
skret	Secrets without the server.	CLI
web-core	Shared web infrastructure package for search, scraping, HTTP security, and st...	Library
wet-mcp	Open-source MCP Server for web search, content extraction, library docs & mul...	MCP

Table of contents

• Features
• Status
• Documentation
• Tools
• Configuration
• Security
• Build from Source
• Trust Model
• License

Features

• Markdown in, Markdown out -- human-readable content instead of raw JSON blocks
• 10 composite tools with 44 actions -- one call instead of chaining 2+ atomic endpoints
• 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 (token) or remote HTTP (OAuth 2.1, no token needed)

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. As of v, the architecture is 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 v+ 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

Full docs at mcp.n24q02m.com/servers/better-notion-mcp/:

• Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
• Modes overview -- stdio / local-relay / remote-relay / remote-oauth
• Multi-user setup -- per-JWT-sub credential model

Install with AI agent -- paste this to your AI coding agent:

Install MCP server better-notion-mcp following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-notion-mcp/setup-with-agent.md

Tools

Tool	Actions	Description
pages	create, get, get_property, update, move, archive, restore, duplicate	Create, read, update, and organize pages
databases	create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database, list_templates	Database CRUD and page management within databases
blocks	get, children, append, update, delete	Read and manipulate block content
users	list, get, me, from_workspace	List and retrieve user information
workspace	info, search	Workspace metadata and cross-workspace search
comments	list, get, create	Page and block comments
content_convert	markdown-to-blocks, blocks-to-markdown	Convert between Markdown and Notion blocks
file_uploads	create, send, complete, retrieve, list	Upload files to Notion
setup	status, start, reset, complete	Credential setup via browser relay, status check, reset, re-resolve
help	-	Get full documentation for any tool

MCP Resources

URI	Description
notion://docs/pages	Page operations reference
notion://docs/databases	Database operations reference
notion://docs/blocks	Block operations reference
notion://docs/users	User operations reference
notion://docs/workspace	Workspace operations reference
notion://docs/comments	Comment operations reference
notion://docs/content_convert	Content conversion reference
notion://docs/file_uploads	File upload reference

Configuration

Variable	Required	Default	Description
NOTION_TOKEN	Yes (stdio)	-	Notion integration token
TRANSPORT_MODE	No	stdio	Set to http for remote mode
PUBLIC_URL	No (http)	-	Server's public URL for OAuth redirect links
NOTION_OAUTH_CLIENT_ID	Yes (http)	-	Notion Public Integration client ID
NOTION_OAUTH_CLIENT_SECRET	Yes (http)	-	Notion Public Integration client secret
MCP_AUTH_DISABLE	No (http)	-	Set to 1 to skip Bearer JWT verification when behind an external auth gateway
PORT	No	0 (OS-assigned)	Server port; set explicitly (e.g. 8080) to bind a fixed port
HOST	No	-	Bind address (http mode)

Self-Hosting (Remote Mode)

You can self-host the remote server with your own Notion OAuth app.

Prerequisites:

1. Create a Public Integration at https://www.notion.so/my-integrations
2. Set the redirect URI to https://your-domain.com/callback
3. Note your client_id and client_secret

docker run -p 8080:8080 \
  -e TRANSPORT_MODE=http \
  -e PORT=8080 \
  -e PUBLIC_URL=https://your-domain.com \
  -e NOTION_OAUTH_CLIENT_ID=your-client-id \
  -e NOTION_OAUTH_CLIENT_SECRET=your-client-secret \
  n24q02m/better-notion-mcp:latest

Security

• OAuth 2.1 + PKCE S256 -- Secure authorization with code challenge
• Rate limiting -- 120 req/min/IP on HTTP transport
• Session owner binding -- IP check + TTL for pending token binds
• Null safety -- Handles Notion API quirks (comments.list 404, undefined rich_text)

Build from Source

git clone https://github.com/n24q02m/better-notion-mcp.git
cd better-notion-mcp
bun install
bun run dev

Trust Model

This plugin implements TC-NearZK (in-memory, ephemeral). See mcp-core/docs/TRUST-MODEL.md for full classification.

Mode	Storage	Encryption	Who can read your data?
HTTP n24q02m-hosted (default)	In-memory Map<sub, OAuthToken>	In-process only	Server process (cleared on restart)
HTTP self-host	Same as hosted	Same	Only you (admin = user)
stdio proxy	~/.better-notion-mcp/config.json	AES-GCM, machine-bound key	Only your OS user (file perm 0600)

License

MIT -- See LICENSE.