Notion

n24q02m35stars

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

1# Notion

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: Apache-2.0
Last checked: 2026-10-27

Stars: 35
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Notion?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Notion need an API key?

No required environment variable is listed on this record.

What transport does Notion use?

Notion runs locally over stdio.

When was Notion last checked?

Last checked 2026-10-27. Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call.

From the publisher

Documentation

notion

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
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
better-notion-mcp	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 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:latest

Install matrix

Client	Install
Claude Code	`/plugin marketplace add n24q02m/claude-plugins` + `/plugin install better-notion-mcp@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: mcp.n24q02m.com/servers/better-notion-mcp/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. 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 --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`)

See Configuration for the full environment-variable reference.

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 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, bearer token)
Multi-user setup -- per-user credential namespace (HTTP mode)

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/better-notion-mcp/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
`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 (~/.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: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`)	`~/.better-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`)	`~/.better-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)	`~/.better-notion/config.json`	File mode 0600; machine key in `~/.better-notion/.secret`	Only your OS user

License

Apache-2.0 -- See LICENSE.

Notion

n24q02m35stars

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

Devops Productivity

Install Run on PlugMCP

GitHub Website

Run on PlugMCP

1# Notion

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: Apache-2.0
Last checked: 2026-10-27

Stars: 35
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Notion?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Notion need an API key?

No required environment variable is listed on this record.

What transport does Notion use?

Notion runs locally over stdio.

When was Notion last checked?

Last checked 2026-10-27. Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call.

From the publisher

Documentation

notion

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
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
better-notion-mcp	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" }
    }
  }
}

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 better-notion-mcp@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: mcp.n24q02m.com/servers/better-notion-mcp/setup/. See the Documentation section for per-client setup (Claude Code, Codex, Gemini CLI, Cursor, Windsurf) and HTTP mode.

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

See Configuration for the full environment-variable reference.

Remote (HTTP mode)

// MCP client config -- remote HTTP (bearer token)
{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

Smithery

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 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, bearer token)
Multi-user setup -- per-user credential namespace (HTTP mode)

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/better-notion-mcp/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
`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 (~/.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: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`)	`~/.better-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`)	`~/.better-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)	`~/.better-notion/config.json`	File mode 0600; machine key in `~/.better-notion/.secret`	Only your OS user

License

Apache-2.0 -- See LICENSE.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Notion?

Does Notion need an API key?

What transport does Notion use?

When was Notion last checked?

Documentation

notion

Table of contents

Features

Install

Install matrix

CLI

Remote (HTTP mode)

Smithery

Status

Documentation

Tools

MCP Resources

Configuration

Self-Hosting (Remote Mode)

Docker Compose (loopback)

Comparison

Security

Build from Source

Trust Model

License

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Notion?

Does Notion need an API key?

What transport does Notion use?

When was Notion last checked?

Documentation

notion

Table of contents

Features

Install

Install matrix

CLI

Remote (HTTP mode)

Smithery

Status

Documentation

Tools

MCP Resources

Configuration

Self-Hosting (Remote Mode)

Docker Compose (loopback)

Comparison

Security

Build from Source

Trust Model

License