better-notion
Better MCP server for Notion API with composite tools optimized for AI agents
Installation
npx @n24q02m/better-notion-mcpAsk AI about better-notion
Powered by Claude Β· Grounded in docs
I know everything about better-notion. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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
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
- 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
helptool - 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
docs/setup-manual.md-- 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-mcpfollowing 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 | Yes (http) | - | Server's public URL for OAuth redirects |
NOTION_OAUTH_CLIENT_ID | Yes (http) | - | Notion Public Integration client ID |
NOTION_OAUTH_CLIENT_SECRET | Yes (http) | - | Notion Public Integration client secret |
DCR_SERVER_SECRET | Yes (http) | - | HMAC secret for stateless client registration |
PORT | No | 8080 | Server port |
Self-Hosting (Remote Mode)
You can self-host the remote server with your own Notion OAuth app.
Prerequisites:
- Create a Public Integration at https://www.notion.so/my-integrations
- Set the redirect URI to
https://your-domain.com/callback - Note your
client_idandclient_secret
docker run -p 8080:8080 \
-e TRANSPORT_MODE=http \
-e PUBLIC_URL=https://your-domain.com \
-e NOTION_OAUTH_CLIENT_ID=your-client-id \
-e NOTION_OAUTH_CLIENT_SECRET=your-client-secret \
-e DCR_SERVER_SECRET=$(openssl rand -hex 32) \
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.
