How do I install the better notion mcp server?

Use a recorded configuration for your client, replace example credential values and paths, and verify the documented runtime. Restart or reconnect the client, then inspect the available tools.

What credentials does it need?

It reads `NOTION_TOKEN`, `PUBLIC_URL`, `NOTION_OAUTH_CLIENT_ID`, `NOTION_OAUTH_CLIENT_SECRET`, `CREDENTIAL_SECRET` from the environment. Store these in your client's env block or a secrets manager — never commit them to a repository — and grant the narrowest scope that still covers your use case.

SSyncDev

Start a project

Better Notion MCP Server

Better MCP server for Notion API with composite tools optimized for AI agents

Remote serverstreamable-httpPython

What is the Better Notion MCP Server?

Better MCP server for Notion API with composite tools optimized for AI agents

What the server does

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)

More MCP options

Compare MCP servers by category, or browse hosted MCP servers if you prefer an endpoint over a local process.

Maintainer setup documentation.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

Tool	What it does
pages	create, get, get_property, update, move, archive, restore, duplicate
databases	create, get, query, create_page, update_page, delete_page, create_data_source, update_data_source, update_database, list_templates
blocks	get, children, append, update, delete
users	list, get, me, from_workspace
workspace	info, search
comments	list, get, create
content_convert	markdown-to-blocks, blocks-to-markdown
file_uploads	create, send, complete, retrieve, list
config	status, setup_status, setup_start, setup_reset, setup_complete, set, cache_clear
config__open_relay	-
help	-

How to install the Better Notion MCP Server

claude mcp add better-notion --env NOTION_TOKEN=your-value --env PUBLIC_URL=your-value --env NOTION_OAUTH_CLIENT_ID=your-value --env NOTION_OAUTH_CLIENT_SECRET=your-value --env CREDENTIAL_SECRET=your-value -- npx -y @n24q02m/better-notion-mcp

Configuration

Variable	Description	Required
NOTION_TOKEN	Credential the server authenticates with.	Yes
PUBLIC_URL	Endpoint or connection string the server talks to.	Yes
NOTION_OAUTH_CLIENT_ID	Configuration value read at startup.	Optional
NOTION_OAUTH_CLIENT_SECRET	Credential the server authenticates with.	Yes
CREDENTIAL_SECRET	Credential the server authenticates with.	Yes

Example prompts to try

“Use Better Notion MCP to pages.”
“Use Better Notion MCP to databases.”
“Use Better Notion MCP to blocks.”

Frequently asked questions

Better MCP server for Notion API with composite tools optimized for AI agents Confirm the tools offered by your installed version in the connected client. Tool availability and permissions depend on the server and account configuration.