Back to Browse
Free
Server data from the Official MCP Registry
Markdown-first MCP server for Notion API with 9 composite tools and 39+ actions.
About
Markdown-first MCP server for Notion API with 9 composite tools and 39+ actions.
Remote endpoints: streamable-http: https://better-notion-mcp.n24q02m.com/mcp
Security Report
10.0
Low Risk10.0Low RiskValid MCP server (2 strong, 1 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry. Trust signals: trusted author (12/12 approved); 3 highly-trusted packages.
Endpoint verified · Requires authentication · 2 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Required
This plugin requests these system permissions. Most are normal for its category.
What You'll Need
Set these up before or after installing:
Notion integration token. Create at https://www.notion.so/my-integrationsRequired
Environment variable: NOTION_TOKEN
How to Install & Connect
Available as Local & Remote
This plugin can run on your machine or connect to a hosted endpoint. during install.
Documentation
View on GitHubFrom the project's GitHub README.
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.
| Project | Tagline | Tag |
|---|---|---|
| better-code-review-graph | Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP |
| better-email-mcp | IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP |
| better-godot-mcp | Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP |
| better-notion-mcp | Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP |
| better-telegram-mcp | Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP |
| claude-plugins | Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace |
| imagine-mcp | Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP |
| jules-task-archiver | Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling |
| mcp-core | Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | 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 |
| tacet | TACET: a self-distilling neuro-symbolic cascade that amortises LLM cost in kn... | Tooling |
| web-core | Shared web infrastructure package for search, scraping, HTTP security, and st... | Library |
| wet-mcp | Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |
Table of contents
- Features
- Status
- Documentation
- Tools
- Configuration
- Comparison
- Security
- Build from Source
- Trust Model
- License
Features
- Markdown in, Markdown out -- human-readable content instead of raw JSON blocks
- 11 composite tools with 45 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. 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
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 |
config | status, setup_start, setup_reset, setup_complete, set, cache_clear | Manage server configuration and credential state via browser relay |
config__open_relay | - | Open the relay configuration form in the browser and return the relay URL + credential state |
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:
- 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 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
Deploy to Cloudflare
Run your own multi-user better-notion-mcp serverless on Cloudflare (Worker + Container + KV).
Prerequisites: a Cloudflare account on the Workers Paid plan and the wrangler CLI.
git clone https://github.com/n24q02m/better-notion-mcp && cd better-notion-mcpwrangler login- Provision the KV namespace and paste its id into
wrangler.jsonc:wrangler kv namespace create better-notion-kv - Set secrets:
wrangler secret put CREDENTIAL_SECRET wrangler secret put NOTION_OAUTH_CLIENT_ID wrangler secret put NOTION_OAUTH_CLIENT_SECRETCREDENTIAL_SECRETis REQUIRED: it derives a deterministic OAuth signing key so user identity survives container recreation. - Push the http image to the CF managed registry and deploy:
wrangler containers push better-notion-mcp:beta wrangler deploy - Complete the Notion OAuth flow in the browser at your Worker domain.
Per-user Notion access tokens are encrypted into KV (MCP_STORAGE_BACKEND=cf-kv),
so they survive scale-to-zero. Do NOT set MCP_AUTH_DISABLE on a shared/public
deployment — it collapses all users into a single token bucket.
Comparison
How better-notion-mcp stacks up against direct competitors in each pillar:
| Capability | better-notion-mcp | makenotion/notion-mcp-server | suekou/mcp-notion-server | awkoy/notion-mcp-server |
|---|---|---|---|---|
| Markdown in / out | Yes (round-trip on pages + blocks) | No (raw Notion JSON) | partial (experimental, append + opt-in convert) | Yes (round-trip + GFM) |
| Composite tool design | Yes (11 tools, 45 actions) | No (22 endpoint-mapped tools) | partial (simplified + raw JSON tools) | Yes (2 dispatch tools, 35+ ops) |
| File uploads to Notion | Yes (file_uploads, single + multi-part) | No | No | Yes (upload_file, single + multi-part) |
| Comments | Yes (comments: list/get/create) | Yes | Yes | Yes |
| Remote HTTP + OAuth 2.1 transport | Yes (per-JWT-sub multi-user) | partial (HTTP + bearer token, no OAuth) | No (stdio token only) | No (stdio token only) |
| Self-hostable | Yes (Docker, own OAuth app) | Yes | Yes | Yes |
| License | MIT | ? | MIT | MIT |
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 the trust model reference 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 (local) | config.enc in the OS config dir (%APPDATA%\mcp\Config\config.enc on Windows, ~/.config/mcp/config.enc on Linux/macOS) | AES-GCM, machine-bound key | Only your OS user |
License
MIT -- See LICENSE.
Reviews
No reviews yet
Be the first to review this server!
More Productivity MCP Servers
Memory
Freeby Modelcontextprotocol · Productivity
Knowledge graph-based persistent memory across sessions
85.9K
Stars
13
Installs
8.0
Security
No ratings yet
Local
Time
Freeby Modelcontextprotocol · Productivity
Time and timezone conversion capabilities for your AI assistant
80.0K
Stars
2
Installs
9.5
Security
No ratings yet
Local
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
137
Stars
516
Installs
8.0
Security
4.8
Local
mcp-creator-python
Freeby mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
-
Stars
71
Installs
10.0
Security
4.6
Local