better-notion-mcp — Claude Code MCP server for Notion in Markdown
Hands an agent access to Notion pages, databases, blocks and comments, with Markdown going in and coming back out instead of raw JSON blocks.
claude mcp add better-notion-mcp -e NOTION_TOKEN=<NOTION_TOKEN> -- npx -y @n24q02m/better-notion-mcpWhat better-notion-mcp does
Getting one thing done through the Notion API usually means chaining several endpoint calls. This server folds that into a single call: 8 composite tools carrying 39 actions cover pages, databases, blocks and comments. Content travels as Markdown both ways, so the agent reads and writes plain text rather than JSON block trees.
Cursor handling and bulk operations ship with the tools, which drops the hand-written loop. Tool descriptions stay short and the agent pulls detail from a separate help tool only when it needs it, trimming token spend by roughly 77%. The npm package is @n24q02m/notion; the older @n24q02m/better-notion-mcp name and the better-notion-mcp command still resolve as an alias.
Two ways to connect: local stdio with an integration token, or the hosted HTTP mode that authenticates over OAuth 2.1 and asks for no token in your config. Stdio needs Node.js 24 or newer — anything older will not start the package through npx. Grab the token at https://www.notion.so/my-integrations; it begins with ntn_.
What it helps with
- read a Notion page and hand back its content as Markdown
- add a database row from text the agent just wrote
- walk a long block list without writing a pagination loop
- pull every comment on a page in one call
- push a batch of rows into a database at once
Example prompts for the agent
- Find the release notes page in Notion and rewrite the migration section as Markdown.
- Create a task in the bugs database for the auth failure and post a comment linking the log.
- List every block on the
Roadmappage and draft a summary from them.
How to install better-notion-mcp
Platform CLI
claude mcp add better-notion-mcp -e NOTION_TOKEN=<NOTION_TOKEN> -- npx -y @n24q02m/better-notion-mcpReplace <…> with your own values
Platform CLI
codex mcp add better-notion-mcp --env NOTION_TOKEN=<NOTION_TOKEN> -- npx -y @n24q02m/better-notion-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"better-notion-mcp": {
"command": "npx",
"args": [
"-y",
"@n24q02m/better-notion-mcp"
],
"env": {
"NOTION_TOKEN": "<NOTION_TOKEN>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"better-notion-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@n24q02m/better-notion-mcp"
],
"env": {
"NOTION_TOKEN": "<NOTION_TOKEN>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e NOTION_TOKEN=<NOTION_TOKEN> better-notion-mcp npx -y @n24q02m/better-notion-mcpReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about better-notion-mcp
How do I install better-notion-mcp in Claude Code?
One command: claude mcp add better-notion-mcp -e NOTION_TOKEN=<NOTION_TOKEN> -- npx -y @n24q02m/better-notion-mcp. Swap the placeholder for your Notion integration token, which starts with ntn_.
What does better-notion-mcp do?
It exposes Notion as Markdown: pages, databases, blocks and comments. The 8 composite tools and 39 actions stand in for a chain of atomic API calls.
Do I need a Notion token and Node.js?
For local stdio, yes to both: Node.js 24 or newer plus an integration token. In HTTP mode the server authenticates with OAuth 2.1 and no token goes into the config.
