M
MCP Directory CURATED DIRECTORY
911 MCP servers indexed
中文
← Back to directory
B

Better Notion MCP Server

Community
Markdown-first Notion for AI agents -- pages, databases, blocks, and comments in one call
How to install ↓ Compare GitHub source repository ↗
Category
Collaboration #5 of 55
Stars
★ 36 Popular
Transport
stdio (local process) · Streamable HTTP
Runtime
Node.js 24+ · Docker
Credentials
API key / credential required
License
Apache-2.0
Last commit
Tools
11
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.

Strongest · Documentation 15/20 Weakest · Reliability 8/20

Reliability
8/20
Security and permissions
12/20
Maintenance
15/20
Documentation
15/20
Setup experience
13/20
Why each score
Reliability 8/20
The README shows CI and codecov badges and claims the architecture is 'now stable', but this static review only has the README and server.json — no actual CI workflow file or test code was available to verify those claims. The Status section itself admits a history of 'multi-process races, browser tab spam, and inconsistent setup UX', indicating past instability rather than a consistently reliable track record. Per the static calibration rule (no score above 12 without verifiable CI/test evidence), a low-to-mid score is given.
Security and permissions 12/20
NOTION_TOKEN is marked required/secret; stdio mode stores it AES-GCM encrypted with a machine-bound key in a local config dir, and HTTP mode uses OAuth 2.1 + PKCE, rate limiting, and session-owner binding — the credential boundaries are reasonably well described, with no sign of plaintext secrets or malicious code, so no red line is triggered. Deductions: the tool surface includes irreversible-leaning operations (archive/restore, delete_page, block delete) with no documented confirmation step; the README's 'Install with AI agent' instruction encourages an agent to fetch and follow install steps from an external URL, an unreviewed remote-instruction pattern that is a soft risk; the Cloudflare self-host path also manages several secrets with limited audit detail. A mid-range score reflects visible-but-incomplete risk mitigation.
Maintenance 15/20
The project uses semantic-release and Renovate for automated dependency updates, is at version 2.40.1 suggesting a fast release cadence, ships both an npm package and a Docker image, and carries a clear MIT license; the repo is not archived. 35 stars and 16 open issues show some user engagement but also a backlog. Deductions: no dedicated SECURITY.md or explicit security-response channel is evidenced, and the same author appears to maintain roughly 19 'sister projects', raising concern about maintainer bandwidth and long-term governance for any single one of them.
Documentation 15/20
Documentation is extensive: table of contents, install, CLI, remote HTTP mode, Smithery, a tools/resources table, a configuration variable table, self-hosting and Cloudflare deployment, a competitor comparison, a security section, and a tiered trust model. Deductions: much operational detail (per-client setup, multi-user configuration) is deferred to an external docs site (mcp.n24q02m.com) that cannot be verified for accuracy in a static review; the 'paste this to your AI agent' install flow directs an agent to fetch and act on instructions from an external page, which is not a reviewable documentation practice.
Setup experience 13/20
Basic stdio setup is simple — one JSON config block, an npx command, and a single env var; the Docker run example is equally clear. However, per the static calibration rule the score is capped without verifiable execution evidence. The remote HTTP/multi-user/Cloudflare self-host path is considerably more involved (OAuth app creation, KV namespace provisioning, multiple secrets, wrangler deploy steps), and the stated Node.js >= 24 requirement adds a compatibility bar for a runtime that may not yet be broadly adopted.

Static review · not runListed 2026-09-07

Read the FMRS scoring method →

Fit and risk

What it can accessUses the networkChanges third-party account dataConnects to a database

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

Setup

Before you start

Runtime：Node.js 24+ · Docker

NOTION_TOKEN requiredsecret Notion integration token created at https://www.notion.so/my-integrations, starts with ntn_; required for stdio mode.
NOTION_OAUTH_CLIENT_SECRET optionalsecret Notion Public Integration client secret; required in HTTP mode.
CREDENTIAL_SECRET optionalsecret Required for Cloudflare deployment; derives the OAuth signing key so user identity survives container recreation.
Other optional settings (7)
TRANSPORT_MODE optional Set to http to switch to remote HTTP mode; optional.
MCP_TRANSPORT optional Same effect as TRANSPORT_MODE; set to http for HTTP transport; optional.
PUBLIC_URL optional Public URL of the self-hosted HTTP server, used for OAuth redirect links.
NOTION_OAUTH_CLIENT_ID optional Notion Public Integration client ID; required in HTTP mode.
MCP_AUTH_DISABLE optional Set to 1 to skip Bearer JWT verification (only behind an external auth gateway).
PORT optional HTTP mode listening port; defaults to an OS-assigned port.
HOST optional Bind address for HTTP mode.
  1. 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.
.mcp.json 
{"mcpServers":{"better-notion-mcp":{"command":"npx","args":["--yes","@n24q02m/better-notion-mcp@latest"],"env":{"NOTION_TOKEN":"ntn_your_token_here"}}}}

Shown for Claude Code. Other clients may use a different file or key (VS Code uses "servers") — the configurator below converts it.

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

Goes in your project's .vscode/mcp.json (VS Code uses a "servers" key).

Terminal
claude mcp add better-notion-mcp -e NOTION_TOKEN=ntn_your_token_here -- npx --yes @n24q02m/better-notion-mcp@latest

Run it in a terminal; replace any <…> placeholders with your own values first.

Generate and validate client config

Check that it works

After starting, the composite tools pages, databases, blocks, etc. should appear in your MCP client's tool list; calling the help tool or the users tool's me action and getting Notion user info confirms the connection works.

Troubleshooting

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

Things to try

Once connected, you can ask your AI assistant things like:

  • Create a page called Project Plan in my Notion workspace with Markdown content.
  • Query my tasks database for all incomplete entries.
  • Convert a given Notion page to Markdown and show it to me.
  • Append a to-do block to a page and add a comment on it.

Tools 11

pages writes
Create, read, update, and organize pages (create/get/get_property/update/move/archive/restore/duplicate)
databases writes
Database CRUD, page management within databases, data source operations, and template listing (10 actions)
blocks writes
Read and manipulate block content (get/children/append/update/delete)
users read-only
List and retrieve user information (list/get/me/from_workspace)
workspace read-only
Workspace metadata and cross-workspace search (info/search)
comments writes
Page comments and discussion replies (list/get/create)
content_convert read-only
Convert between Markdown and Notion blocks in both directions
file_uploads writes
Upload files to Notion, single or multi-part (create/send/complete/retrieve/list)
Show 3 more tools
config read-only
Inspect and manage credential state and configuration lifecycle
config__open_relay read-only
Open the relay configuration form in the browser and return the relay URL plus credential state
help read-only
Get full documentation for any composite tool (via tool_name parameter)

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 Code
Cursor
Codex
Gemini CLI
Windsurf

Listed from the project's documentation, not tested by this site.

Overview

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.

Similar servers

Compare with other MCP servers

Source revision 6f8771913eb8 Data synced 2026-10-19 Read the FMRS scoring method