better-notion-mcp

Markdown öncelikli Notion MCP sunucusu, 9 bileşik araç, 39 eylem ve katmanlı dokümanlarla ~%77 token azaltımı sunar.

Dokümantasyon

notion

mcp-name: io.github.n24q02m/notion

Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call.

Sister projects from n24q02m (click to expand)

Project	Tagline	Tag
agent-chat-plugin	Peer AI agents chat in a shared folder — no human relay, no orchestrator, wor...	Tooling
better-code-review-graph	Knowledge graph for token-efficient code reviews -- semantic search and call-...	MCP
better-drive	2-way Google Drive sync with .driveignore filter — rclone engine, Windows tray	Tooling
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
notion	Markdown-first Notion for AI agents -- pages, databases, blocks, and comments...	MCP
better-semantic-release	Drop-in python-semantic-release fork with built-in release-safety guards (orp...	Tooling
better-telegram-mcp	Telegram for AI agents -- messages, chats, media, and contacts across both bo...	MCP
better-workspace-mcp	Google Workspace MCP server (Docs/Drive/Calendar/Gmail/Sheets/Slides/Tasks/Ch...	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	A self-distilling neuro-symbolic cascade that amortises LLM cost across knowl...	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

Features
Install
CLI
Remote (HTTP mode)
Smithery
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
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)

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": {
    "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 is io.github.n24q02m/notion, and the legacy better-notion-mcp command is kept as an alias of notion. The registry still lists the pre-rename io.github.n24q02m/better-notion-mcp entry; that entry stays frozen and is never republished.

Or run the published Docker image (stdio):

docker run --rm -i -e NOTION_TOKEN=ntn_your_token_here n24q02m/notion:latest

Install matrix

Client	Install
Claude Code	`/plugin marketplace add n24q02m/claude-plugins` + `/plugin install notion@n24q02m-plugins` (stdio; prompts for `NOTION_TOKEN`), or an `mcpServers` entry in `.mcp.json` / client settings
Codex CLI	`[mcp_servers.notion]` block in `~/.codex/config.toml` (stdio `command`/`args` or HTTP `type`/`url`)
OpenCode	`mcpServers` block in `opencode.json`
Cursor / Windsurf / Gemini CLI / any MCP client	`mcpServers` JSON in the client's config — same shape as the example above

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.

CLI

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. Every tool is also callable directly (see Tool commands); auth stores the Notion integration token, and 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 --http

Argument / env	Effect
(none)	stdio transport (default); requires `NOTION_TOKEN`
`--http`	HTTP transport; auth chosen by `MCP_AUTH_MODE` (`multi` default, `token`, or `no-auth`)

Tool commands

Every MCP tool has a CLI subcommand, and the subcommand runs the same handler the MCP tool runs -- notion pages get and the pages tool both go through invokeTool and src/tools/composite/pages.ts. Flags come from the tool's own JSON input schema: property names in kebab-case (--page-id), the snake_case spelling also accepted, arrays as a comma list or a repeated flag, and object / array-of-object flags as JSON. A tool's action is accepted as the first positional argument or as --action.

Add --json for compact JSON on stdout; without it the result prints as a readable block. Tool failures exit 1 with a one-line message on stderr, usage errors exit 2. content_convert, help, and config need no token; every other tool resolves the token exactly as the server does (NOTION_TOKEN, else the token stored by notion auth).

Tool	Command	Example
`pages`	`notion pages <action> [flags]`	`notion pages get --page-id <page-id> --json`
`databases`	`notion databases <action> [flags]`	`notion databases query --database-id <db-id> --limit 5`
`blocks`	`notion blocks <action> --block-id <id>`	`notion blocks append --block-id <block-id> --content '## Update'`
`users`	`notion users <action>`	`notion users me`
`workspace`	`notion workspace <action> [flags]`	`notion workspace search --query roadmap`
`comments`	`notion comments <action> [flags]`	`notion comments list --page-id <page-id>`
`content_convert`	`notion content_convert --direction <d> --content <text>`	`notion content_convert --direction markdown-to-blocks --content '# Title'`
`file_uploads`	`notion file_uploads <action> [flags]`	`notion file_uploads list --limit 10`
`help`	`notion help <tool>`	`notion help databases`
`config`	`notion config-tool <action>`	`notion config-tool status`

# Read a page as JSON without an MCP client
notion pages get --page-id 2f1c... --json

# Convert markdown offline (no token)
notion content_convert --direction markdown-to-blocks --content '# Title'

# Credential state and per-tool documentation (no token)
notion config-tool status --json
notion help pages

# Print one tool's flags and actions
notion pages --help

notion --help lists the tool commands and the operator commands as separate groups. One name needs a suffix: the MCP config tool is notion config-tool, because the operator notion config status / notion config delete --yes commands own the plain word and manage the stored credential file. The tool covers the same lifecycle (status, setup_start, setup_complete, setup_reset) as data instead of as operator commands; its set and cache_clear actions are no-ops for Notion.

Remote (HTTP mode)

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).

Smithery

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).

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 -- 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.

Documentation

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 notion following the steps at https://raw.githubusercontent.com/n24q02m/claude-plugins/main/plugins/notion/setup-with-agent.md

Tools

Eight composite Notion tools (39 actions) plus two infrastructure tools (config, 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_status`, `setup_start`, `setup_reset`, `setup_complete`, `set`, `cache_clear`	Inspect and manage credential state and configuration lifecycle
`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`)
`MCP_AUTH_MODE`	No (http)	`multi`	`multi` (per-user tokens from `MCP_USERS_FILE`), `token` (one shared token, needs `MCP_AUTH_TOKEN_HASH`), or `no-auth` (trusted/local use only)
`MCP_USERS_FILE`	No (http, multi)	`~/.hull/users.toml`	Users file for `multi` mode
`NOTION_DATA_DIR`	No	`$HOME`	Base directory for the credential store. Tokens live in `<dir>/.notion/` (`config.json`, or `subs/<namespace>/config.json` in multi-user HTTP); a store an earlier release wrote under `<dir>/.better-notion/` is copied forward on startup. A relative value is resolved under `$HOME` and must stay inside it; use an absolute path (e.g. `/data`) to point at a mounted volume
`MCP_AUTH_TOKEN_HASH`	Yes (token mode)	-	`scrypt$` hash of the shared token (mint with `token hash`)
`MCP_RPM`	No (token mode)	-	Optional per-minute request cap in token mode
`PORT`	No	`0` (OS-assigned)	Server port; set explicitly (e.g. `8080`) to bind a fixed port
`HOST`	No	`127.0.0.1`	Bind address (http mode)

Self-Hosting (Remote 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 (~/.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:latest

Docker Compose (loopback)

docker-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 up

The 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.

Comparison

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 (`file_uploads`, single + multi-part)	No	No	Yes (`upload_file`, single + multi-part)
Comments	Yes (`comments`: list/get/create)	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

Security

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)

Build from Source

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

Trust Model

Credentials are never sent to n24q02m: there is no hosted endpoint.

Mode	Storage	Protection	Who can read your data?
HTTP self-host (`multi`)	`~/.notion/subs/<ns>/config.json` on the server host	File mode 0600 under the server's data dir	The server operator and anyone with access to that host
HTTP self-host (`token`)	`~/.notion/config.json` on the server host	File mode 0600 under the server's data dir	The server operator and anyone with access to that host
stdio (local)	`~/.notion/config.json`	File mode 0600; machine key in `~/.notion/.secret`	Only your OS user

License

Apache-2.0 -- See LICENSE.