What can you do with this server?

Better Notion MCP is a Markdown-first MCP server that provides AI-optimized, composite tools for interacting with Notion workspaces through human-readable markdown instead of raw JSON blocks. Core Capabilities: * Pages: Create, read, update, archive, restore, and duplicate pages with markdown content; set titles, icons, covers, and properties; append or prepend content; batch operations * Databases: Create and manage databases with custom schemas; query with filters, sorts, and text search; create, update, and delete database pages; manage data sources; bulk operations * Blocks: Get, append, update, and delete individual blocks; supports headings, paragraphs, lists, code blocks, quotes, dividers, and inline formatting * Users: List all users, get specific user details by ID, retrieve current authenticated user info * Workspace: Get workspace information; search across pages and databases with filtering and sorting options * Comments: List existing comments, create new comment discussions, reply to existing threads * Content Conversion: Convert between markdown and Notion blocks format (automatic in most tools) * Help: Get on-demand detailed documentation for any tool Key Advantages: * Markdown-first for human readability and AI processing * Composite operations replacing multiple API requests * Auto-pagination without manual cursor management * Native batch operation support * ~77% token reduction through tiered descriptions and on-demand documentation

Which integrations are available for this server?

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.

How do I use Better Notion MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. 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.

Better Notion MCP

by n24q02m

Overview Schema Related Servers Score Discussions

TypeScript

Remote

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.

codecov npm Docker License: MIT

TypeScript Node.js Notion semantic-release Renovate

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

Related MCP server: WET - Web Extended Toolkit

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.

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, integration token) and HTTP (remote, OAuth 2.1)
Multi-user setup -- per-JWT-sub credential model (HTTP mode)

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

Eight composite Notion tools (39 actions) plus three infrastructure tools (config, config__open_relay, help):

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 comments and discussion replies
`content_convert`	`markdown-to-blocks`, `blocks-to-markdown`	Convert between Markdown and Notion blocks (uses a `direction` parameter)
`file_uploads`	`create`, `send`, `complete`, `retrieve`, `list`	Upload files to Notion (single or multi-part)
`config`	`status`, `setup_start`, `setup_reset`, `setup_complete`, `set`, `cache_clear`	Inspect and manage credential state and configuration lifecycle
`config__open_relay`	-	Open the relay configuration form in the browser and return the relay URL + credential state
`help`	-	Get full documentation for any composite tool (`tool_name` parameter)

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` / `MCP_TRANSPORT`	No	`stdio`	Set either to `http` for remote mode (or pass `--http`)
`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_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

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 — required for Containers (the Cloudflare free tier does not include Containers) — and the wrangler CLI.

git clone https://github.com/n24q02m/better-notion-mcp && cd better-notion-mcp
wrangler 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_SECRET
```
CREDENTIAL_SECRET is 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 (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 (`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.

Install Server

license - permissive license

quality

maintenance

How are these scores calculated?

Maintenance

–Maintainers

1dResponse time

1dRelease cycle

188Releases (12mo)

Commit activity

Issues opened vs closed

Resources

Need Help?

Related Servers

Tools

View all tools

Appeared in Searches

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/n24q02m/better-notion-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

Better Notion MCP

Table of contents

Features

Install

Status

Documentation

Tools

MCP Resources

Configuration

Self-Hosting (Remote Mode)

Deploy to Cloudflare

Comparison

Security

Build from Source

Trust Model

License

Maintenance

Resources

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API