Better Notion MCP Server

Community

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

★ 35 Stars Category · Collaboration Popular

63FMRS · C

A mature, broad-coverage third-party Notion MCP server: round-trip Markdown conversion, 8 composite tools with 39 actions, auto-pagination and bulk operations, dual stdio/OAuth 2.1 HTTP transports, npm and Docker distribution, Cloudflare deployability, plus clear comparison tables and security notes. Well suited to AI-agent-driven Notion workflows, provided you accept community maintenance and safeguard your integration token.

Reliability

8/20

Security and permissions

12/20

Maintenance

15/20

Documentation

15/20

Setup experience

13/20

Read the FMRS scoring method →

Better Notion MCP is an open-source (MIT) Model Context Protocol server maintained by n24q02m; it is not an official Notion product. It wraps the Notion API with Markdown as the input/output format, offering 8 composite tools (39 actions) plus config, config__open_relay, and help infrastructure tools, with auto-pagination and bulk operations and a claimed ~77% token reduction via tiered optimization. It supports dual transport -- local stdio (integration token) and remote HTTP (OAuth 2.1) -- runs from an npm package or Docker image, and can be self-hosted on Cloudflare Workers.

Tools

pages

Create, read, update, and organize pages (create/get/get_property/update/move/archive/restore/duplicate)

databases

Database CRUD, page management within databases, data source operations, and template listing (10 actions)

blocks

Read and manipulate block content (get/children/append/update/delete)

users

List and retrieve user information (list/get/me/from_workspace)

workspace

Workspace metadata and cross-workspace search (info/search)

comments

Page comments and discussion replies (list/get/create)

content_convert

Convert between Markdown and Notion blocks in both directions

file_uploads

Upload files to Notion, single or multi-part (create/send/complete/retrieve/list)

config

Inspect and manage credential state and configuration lifecycle

config__open_relay

Open the relay configuration form in the browser and return the relay URL plus credential state

help

Get full documentation for any composite tool (via tool_name parameter)

Setup

Create an integration at https://www.notion.so/my-integrations and get a token starting with ntn_. 2. With Node.js >= 24, configure your MCP client with command: npx, args: ["--yes","@n24q02m/better-notion-mcp@latest"], and env NOTION_TOKEN; or run Docker: docker run --rm -i -e NOTION_TOKEN=... n24q02m/better-notion-mcp:latest. For remote HTTP mode pass --http and provide OAuth client ID/secret; the first connection opens Notion's OAuth consent screen.

claude_desktop_config.json

{"mcpServers":{"better-notion-mcp":{"command":"npx","args":["--yes","@n24q02m/better-notion-mcp@latest"],"env":{"NOTION_TOKEN":"ntn_your_token_here"}}}}

Generate and validate client config

Fit and risk

Best for

Heavy Notion users who want Markdown-based collaboration with AI agents
Developers integrating Notion workflows into Claude Code, Cursor, and similar clients
Automation scenarios needing the full Notion surface: uploads, comments, block-level edits

Not for

Users seeking a server officially supported by Notion (this is third-party open source)
Users unwilling to grant a Notion integration token or complete OAuth consent
Environments with Node.js < 24 and no Docker available

Required permissions

Requires a Notion integration token (ntn_ prefix); it can only access pages explicitly shared with the integration
HTTP mode requires a Notion Public Integration OAuth client ID and secret
Token is passed via the NOTION_TOKEN environment variable and is a secret

Risks and side effects

Third-party project not maintained by Notion; review the code yourself
In stdio mode the token is stored AES-GCM encrypted in a local config file, but the integration token itself is broad in scope
In hosted HTTP mode tokens live only in process memory and are cleared on restart
Setting MCP_AUTH_DISABLE=1 on a shared/public deployment collapses all users into a single token bucket -- a serious risk
Earlier versions had instability around credential handling and daemon-bridge auto-spawn; use the latest release

Troubleshooting

Verify NOTION_TOKEN is set, starts with ntn_, and target pages are shared with the integration in Notion
Confirm Node.js >= 24 when using npx
For remote mode set TRANSPORT_MODE=http, PUBLIC_URL, and NOTION_OAUTH_CLIENT_ID/SECRET correctly
On HTTP 401/auth failures, check that the OAuth redirect URI matches the Notion Public Integration configuration
After upgrading from older versions, follow the current setup guide -- most prior workarounds are obsolete

Use cases

Create and organize Notion pages and databases in bulk via natural language or Markdown

Query and update Notion content directly inside AI coding agents like Claude Code and Cursor

Automate comment management and file uploads

Self-host a multi-user remote Notion gateway (OAuth 2.1)

Supported clients

Claude CodeFull support

CursorFull support

CodexFull support

Gemini CLIFull support

WindsurfFull support

SmitheryFull support

Related MCP servers

Compare with other MCP servers