better-notion

Better Notion MCP is a Markdown-first bridge that consolidates Notion's API into composite actions optimized for AI agents. It exposes a suite of tools under the Notion API umbrella (pages, databases, blocks, users, workspace, comments, content_convert, file_uploads, and a help tool) so agents can perform high-level operations with a single call. To run it, provide a Notion integration token via the NOTION_TOKEN environment variable and start the MCP server using the recommended package manager runner (bun in the default setup). Once running, clients can invoke composite actions like creating a page, querying a database, updating blocks, or converting content between Markdown and Notion blocks, all through the unified 9-tools set designed for efficient AI usage.

You can rely on the built-in tooling surface including: 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), and help (for full tool docs). The documentation-aligned design enables agents to discover capabilities on demand via the help tool when needed.

Prerequisites:

• Node.js 24+ or Bun (as used in this MCP setup)
• Bun installed (recommended for the default run path)
• A Notion integration token with appropriate permissions

Option A: Quick-start using Bun (default in this repo)

1. Install Bun if you don’t have it yet: https://bun.sh/
2. Start the MCP server using the provided configuration:

# Ensure you have the NOTION_TOKEN ready
export NOTION_TOKEN=your_notion_token_here

# Run the MCP server (default using Bun + package from npm)
bun x @n24q02m/better-notion-mcp@latest

3. The server will start and listen for MCP requests. Use your MCP client to send requests to the running instance.

Option B: Docker-based run (alternative)

1. Pull and run the Docker image with the required env var:

export NOTION_TOKEN=your_notion_token_here

docker run -i --rm --name mcp-notion -e NOTION_TOKEN="$NOTION_TOKEN" n24q02m/better-notion-mcp:latest

2. Point your MCP client to the container’s exposed port as configured by the image (default networking).

Notes and tips:

• NOTION_TOKEN is required and should correspond to a Notion integration with access to the relevant pages/databases.
• The recommended run mode is Bun with the package name @n24q02m/better-notion-mcp@latest; alternative runners (npx, pnpm dlx, yarn dlx) are supported and documented in the readme.
• If you’re using Docker, pass the NOTION_TOKEN via an environment variable into the container.
• The server exposes a suite of 9 tools with 39 actions, designed for AI agent workflows; consult the help tool for on-demand full tool docs.
• For local builds from source, ensure you have Node.js 24+ and Bun installed; follow the repository’s Build from Source instructions if you want to develop or contribute.