Better Notion MCP gives AI agents a markdown-first interface to Notion — pages, databases, blocks, users, workspace, comments, and file uploads via 8 composite tools (39 actions) plus config and help.
pages — create, get (markdown content, bounded reads with cursor), get_property, update (title/content/append_content/properties/icon/cover/archive), move, archive/restore, duplicate; simple property values auto-convert to Notion format
databases — create, get, query (filters, sorts, limit, smart search), bulk create_page/update_page/delete_page, create/update data sources, update database, list templates; accepts database_id or data_source_id
blocks — get a block, list children, append markdown (start / end / after a given block), update text blocks, delete blocks
users — list workspace users, get one user, get the current bot (me), extract users from accessible pages
workspace — workspace info (name, plan, bot user) and search across pages and databases shared with the integration
comments — list a page's comments, get a comment, create a comment or reply to a discussion
content_convert — round-trip Markdown ↔ Notion block JSON for preview/validation (headings, lists, to-dos, code, callouts, toggles, tables, columns, embeds, equations, inline formatting)
file_uploads — create, send (base64), complete, retrieve, list uploads; single or multi-part for files over 20 MB
config / help — inspect and manage credential/setup state; fetch full per-tool docs on demand to save tokens
Workflow conveniences — markdown in/out instead of raw JSON, auto-pagination, bulk operations, and dual transport (local stdio with NOTION_TOKEN, or remote HTTP with per-user or shared bearer-token auth)
Provides markdown-first tools for managing Notion workspaces, including page lifecycle operations (create, update, archive, duplicate), database management with bulk operations, block-level editing, user management, workspace search, and comment operations. Features composite actions that combine multiple operations, auto-pagination, and smart database queries.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Better Notion MCP create a new page in my 'Projects' database with title 'Q4 Planning' and markdown content for our quarterly goals"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor... | Tooling | |
Knowledge graph for token-efficient code reviews -- semantic search and call-... | MCP | |
2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray | Tooling | |
IMAP/SMTP email for AI agents -- read, send, organize folders, and manage att... | MCP | |
Composite MCP server for Godot Engine -- 17 composite tools for AI-assisted g... | MCP | |
Markdown-first Notion for AI agents -- pages, databases, blocks, and comments... | MCP | |
Drop-in python-semantic-release fork with built-in release-safety guards (orp... | Tooling | |
Telegram for AI agents -- messages, chats, media, and contacts across both bo... | MCP | |
Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch... | MCP | |
Claude Code plugin marketplace for the n24q02m MCP servers -- install web sea... | Marketplace | |
Image and video understanding + generation for AI agents -- across Gemini, Op... | MCP | |
Chrome Extension for bulk operations on Jules tasks via batchexecute API -- a... | Tooling | |
Shared foundation for building MCP servers -- Streamable HTTP transport, OAut... | MCP | |
Persistent AI memory with hybrid search and embedded sync. Open, free, unlimi... | MCP | |
Lightweight Qwen3 text embedding and reranking via ONNX Runtime and GGUF | Library | |
Secrets without the server. | CLI | |
A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl... | Tooling | |
Shared web infrastructure package for search, scraping, HTTP security, and st... | Library | |
Open-source MCP server for AI agents: web search, content extraction, and lib... | MCP |
Related MCP server: WET - Web Extended Toolkit
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 and help)
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 (per-user or shared bearer token)
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": {
"notion": {
"command": "npx",
"args": ["--yes", "@n24q02m/notion@latest"],
"env": { "NOTION_TOKEN": "ntn_your_token_here" }
}
}
}The package is @n24q02m/notion (formerly @n24q02m/better-notion-mcp;
old package receives one final release then freezes). The MCP Registry id stays
io.github.n24q02m/better-notion-mcp, and the legacy better-notion-mcp
command is kept as an alias of notion.
Or run the published Docker image (stdio):
docker run --rm -i -e NOTION_TOKEN=ntn_your_token_here n24q02m/notion:latestClient | Install |
Claude Code |
|
Codex CLI |
|
OpenCode |
|
Cursor / Windsurf / Gemini CLI / any MCP client |
|
Full per-client walkthroughs: docs.n24q02m.com/servers/notion/setup/. See the Documentation section for per-client setup (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) and HTTP mode.
Installing the package exposes a notion binary (plus the legacy better-notion-mcp alias; run it with npx or after a global install). With no arguments 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. Subcommands: auth stores the Notion integration token; config, status, logout, doctor, and token come from the shared hull CLI.
# Start the stdio server (default transport; requires NOTION_TOKEN)
NOTION_TOKEN=ntn_your_token_here npx --yes @n24q02m/notion@latest
# Start the remote HTTP server (bearer token) instead of stdio
npx --yes @n24q02m/notion@latest --httpArgument / env | Effect |
(none) | stdio transport (default); requires |
| HTTP transport; auth chosen by |
See Configuration for the full environment-variable reference.
Deployed with the HTTP transport, the server is a remote endpoint gated by bearer-token auth -- no integration token in the server config. Point an MCP client that supports remote HTTP servers at the host you deployed it on:
// MCP client config -- remote HTTP (bearer token)
{
"mcpServers": {
"notion": {
"type": "http",
"url": "https://<your-host>/mcp",
"headers": { "Authorization": "Bearer <your-token>" }
}
}
}In multi mode (default) each user is listed in the users file (MCP_USERS_FILE, default ~/.hull/users.toml) and gets their own token and credential namespace. In token mode every client shares one token whose scrypt hash is set in MCP_AUTH_TOKEN_HASH. To stand up such an instance, see Self-Hosting (Remote Mode).
The repo ships a smithery.yaml config for Smithery. Smithery launches the server over stdio (npx -y @n24q02m/notion) and requires no install-time config -- provide your Notion credentials at runtime through NOTION_TOKEN or the config tool (see Configuration).
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 -- Web search + content extraction
mnemo -- Persistent AI memory
imagine-mcp -- Image/video understanding + generation
email -- Email management
telegram -- Telegram
better-godot-mcp -- Godot Engine
crg -- Code review knowledge graph
All plugins share the same architecture -- install once, learn pattern transfers.
Full docs at docs.n24q02m.com/servers/notion/:
Setup -- install methods for Claude Code, Codex, Gemini CLI, Cursor, Windsurf, mcp.json
Install with AI agent -- paste this to your AI coding agent:
Install MCP server
notionfollowing the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/better-notion-mcp/setup-with-agent.md
Eight composite Notion tools (39 actions) plus two infrastructure tools (config, help):
Tool | Actions | Description |
|
| Create, read, update, and organize pages |
|
| Database CRUD and page management within databases |
|
| Read and manipulate block content |
|
| List and retrieve user information |
|
| Workspace metadata and cross-workspace search |
|
| Page comments and discussion replies |
|
| Convert between Markdown and Notion blocks (uses a |
|
| Upload files to Notion (single or multi-part) |
|
| Inspect and manage credential state and configuration lifecycle |
| - | Get full documentation for any composite tool ( |
URI | Description |
| Page operations reference |
| Database operations reference |
| Block operations reference |
| User operations reference |
| Workspace operations reference |
| Comment operations reference |
| Content conversion reference |
| File upload reference |
Variable | Required | Default | Description |
| Yes (stdio) | - | Notion integration token |
| No |
| Set either to |
| No (http) |
|
|
| No (http, multi) |
| Users file for |
| Yes (token mode) | - |
|
| No (token mode) | - | Optional per-minute request cap in token mode |
| No |
| Server port; set explicitly (e.g. |
| No |
| Bind address (http mode) |
Run the HTTP server on your own host and choose an auth mode with MCP_AUTH_MODE:
multi (default): list each user in MCP_USERS_FILE; each user's Notion token is stored in their own namespace (~/.better-notion/subs/<ns>/config.json).
token: one shared bearer token. Mint the hash with token hash and pass it as MCP_AUTH_TOKEN_HASH.
no-auth: no bearer check. Use only on a trusted local network.
docker run -p 8080:8080 \
-e TRANSPORT_MODE=http \
-e PORT=8080 \
-e MCP_AUTH_MODE=token \
-e MCP_AUTH_TOKEN_HASH='scrypt$...' \
n24q02m/notion:latestdocker-compose.http.yml builds the http image target and publishes it on the host loopback interface only (127.0.0.1:8081), so the server is never reachable from other machines directly:
export MCP_AUTH_MODE=token
export MCP_AUTH_TOKEN_HASH='scrypt$...'
docker compose -f docker-compose.http.yml upThe server listens on http://localhost:8081/mcp. To expose it, put your own TLS reverse proxy in front of the loopback port.
Release images are published multi-arch (amd64 + arm64) to Docker Hub (n24q02m/notion) and GHCR (ghcr.io/n24q02m/notion). There is no n24q02m-hosted HTTP endpoint.
How notion stacks up against direct competitors in each pillar:
Capability | notion | 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 (8 composite tools, 39 actions) | No (22 endpoint-mapped tools) | partial (simplified + raw JSON tools) | Yes (2 dispatch tools, 35+ ops) |
File uploads to Notion | Yes ( | No | No | Yes ( |
Comments | Yes ( | Yes | Yes | Yes |
Remote HTTP + bearer-token auth | Yes (per-user namespaces or shared token) | partial (HTTP + bearer token) | No (stdio token only) | No (stdio token only) |
Self-hostable | Yes (Docker, own bearer token) | Yes | Yes | Yes |
License | Apache-2.0 | ? | MIT | MIT |
Bearer token auth -- per-user tokens (multi) or one scrypt-hashed shared token (token)
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)
git clone https://github.com/n24q02m/notion.git
cd notion
bun install
bun run devCredentials are never sent to n24q02m: there is no hosted endpoint.
Mode | Storage | Protection | Who can read your data? |
HTTP self-host ( |
| File mode 0600 under the server's data dir | The server operator and anyone with access to that host |
HTTP self-host ( |
| File mode 0600 under the server's data dir | The server operator and anyone with access to that host |
stdio (local) |
| File mode 0600; machine key in | Only your OS user |
Apache-2.0 -- See LICENSE.
Read and modify block-level content within pages.
Actions (required params -> optional):
get (block_id): retrieve single block
children (block_id): list child blocks
append (block_id, content -> position, after_block_id): add markdown content at position
update (block_id, content): replace text block content
delete (block_id): remove block
Use pages for page metadata/properties. Page IDs are valid block IDs. update only works on text blocks (paragraph, headings, lists, quote, to_do, code). Image/file blocks contain signed URLs (1h expiry). append supports position: "start" (prepend), "end" (default), "after_block" (requires after_block_id).
Inputs: action (required), block_id (required), content, position, +1 more. Returns: object
Manage page comments.
Actions (required params -> optional):
list (page_id): all comments on a page
get (comment_id): single comment
create (content -> page_id for new discussion, discussion_id for reply)
Inputs: action (required), content, page_id, comment_id, +1 more. Returns: object
Manage server configuration and credential state.
Actions:
status: current credential state and token source
setup_status: credential/setup state only (alias-equivalent to status for notion; kept for cross-server parity)
setup_start (-> force): show how to store a Notion token with notion auth
setup_reset: clear stored credentials, return to awaiting_setup
setup_complete: re-check credentials after external config changes
set: update a runtime setting (notion has no mutable settings; returns info)
cache_clear: clear any cached state (no-op for notion)
Inputs: action (required), key, force, value. Returns: object
Convert between markdown and Notion block JSON. Directions: markdown-to-blocks (input: markdown string), blocks-to-markdown (input: JSON array of Notion blocks or JSON string). Most tools (pages, blocks) handle markdown automatically -- use this only for preview/validation. Supported markdown: headings, lists, to-do, code blocks, blockquotes, dividers, callouts (> [!NOTE]), toggles (), tables, images, bookmarks, embeds, equations ($$), columns (:::columns), [toc], [breadcrumb]. Inline: bold, italic, code, strike, link.
Inputs: content (required), direction (required). Returns: object
Database schema, query, and bulk row operations.
Actions (required params -> optional):
create (parent_id -> title, properties, is_inline, icon, cover)
get (database_id)
query (database_id -> filters, sorts, limit, search)
create_page (database_id, pages[{properties}])
update_page (database_id, page_id, page_properties)
delete_page (database_id, page_ids)
create_data_source / update_data_source / update_database / list_templates
Use pages instead for single page CRUD. Accepts both database_id (from URL) and data_source_id (from workspace search) -- auto-resolved.
Inputs: action (required), icon, cover, limit, +14 more. Returns: object
Upload files to Notion.
Actions (required params -> optional):
create (filename -> content_type, mode="single"|"multi_part", number_of_parts)
send (file_upload_id, file_content -> part_number): base64-encoded content
complete (file_upload_id)
retrieve (file_upload_id)
list (-> limit)
Max 20MB direct, multi-part for larger files.
Inputs: action (required), mode, limit, filename, +5 more. Returns: object
Get full documentation for a tool. Use when compressed descriptions are insufficient.
Inputs: tool_name (required).
Page CRUD for individual pages and database rows.
Actions (required params -> optional):
create (parent_id -> title, content, properties, icon, cover)
get (page_id -> content_limit, content_cursor): returns markdown content; bounded reads return content_truncated and next_cursor
get_property (page_id, property_id)
update (page_id -> title, content, append_content, properties, icon, cover, archived)
move (page_id, parent_id)
archive (page_id) / restore (page_id)
duplicate (page_id -> parent_id)
Use databases instead for querying or bulk row operations. Property format: simple values auto-convert -- string for title/rich_text/select/status, number for number, boolean for checkbox, string[] for multi_select, ISO date "2025-01-15" for date. Example: properties: {"Name": "My Page", "Status": "In Progress", "Tags": ["urgent", "work"]}
Inputs: action (required), icon, cover, title, +10 more. Returns: object
Get user information.
Actions (required params):
list: all workspace users (requires admin permissions)
get (user_id): single user info
me: current bot/integration user
from_workspace: extract users from accessible pages (use if list fails)
Inputs: action (required), user_id. Returns: object
Search workspace and get workspace info.
Actions (required params -> optional):
info: workspace name, plan, and bot user
search (-> query, filter.object="page"|"data_source", sort, limit): find pages/databases shared with integration
Inputs: action (required), sort, limit, query, +1 more. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 10 tools
Tools are largely separated by Notion resource (pages, blocks, databases, comments, users, workspace), so most selections are clear. There is some overlap between pages.update/append_content and blocks.append, and between databases row operations and pages CRUD, though the descriptions provide guidance.
The dominant pattern is resource-noun tools with action subcommands, which is predictable and readable. Minor deviations include singular config/workspace, plural file_uploads/users/pages, and utility names like help and content_convert.
At 10 tools, the server is well-scoped for the Notion API surface. Each tool groups a meaningful resource area without forcing an excessive number of separate tools.
The surface covers the main Notion workflows: pages, blocks, databases, comments, users, workspace search, file uploads, and content conversion. Minor gaps or unclear areas remain around database-level archive/delete and block reordering/moving.
Hosted Notion MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MCP-native open-source Notion alternative: read & write pages, databases and kanban boards.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
