Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call.
Markdown-first Model Context Protocol (MCP) server for the Notion API. It exposes 8 composite tools and 39 actions to work with pages, databases, blocks, and comments via a single call, using Markdown as the primary format for AI agents.
🛠️ Key Features
Notion API integration
Markdown-first interface for AI agents
8 composite tools
39 actions covering pages, databases, blocks, and comments
🚀 Use Cases
Create or update Notion content for AI agents using Markdown
Retrieve and manage Notion pages and databases
Operate on Notion blocks and comments through MCP actions
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):
bash
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
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.
bash
# 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).
# 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:
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.
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-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:
bash
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