easy-notion — Claude Code MCP server: Notion as markdown
An MCP server that hands your agent Notion pages as plain markdown. Useful when you read and edit pages instead of parsing raw JSON.
claude mcp add --env NOTION_TOKEN=<NOTION_TOKEN> --env NOTION_ROOT_PAGE_ID=<NOTION_ROOT_PAGE_ID> --transport stdio easy-notion -- npx -y easy-notion-mcpWhat easy-notion does
The agent writes markdown; the server turns it into Notion blocks and back. It ships 43 tools and covers 24 block types, among them toggles, columns, callouts, equations, embeds, tables, file uploads and task lists. Reading a page costs far fewer response tokens than the official Notion server, since the payload skips per-block bookkeeping such as block IDs, timestamps and author objects. That omission is where the saving comes from, not the encoding.
Installation runs through npx, and a Notion token is required either way. Create a Notion integration, copy the token, then share the pages with it — otherwise the server sees nothing. In Claude the token goes in with the -e flag and stays in the config file, leaving your shell and rcfiles alone. A default parent page for create_page is set with NOTION_ROOT_PAGE_ID.
CLI profiles keep separate integrations for different permission modes, say read-only and read-write, and store environment variable names rather than raw tokens. They live in ~/.config/easy-notion-mcp/profiles.json. Reach for them when an agent needs Notion without loading the whole MCP tool surface.
What it helps with
- read a Notion page and get it back as markdown
- build a page with nested blocks from a markdown file
- rewrite a page while keeping its formatting
- upload a file to Notion from a
file:///pathreference - give an agent read-only access to Notion
Example prompts for the agent
- Read the Notion page and show me its contents as markdown
- Create a Notion page from
notes.md - Update the Notion page: replace the text in the first section
How to install easy-notion
Platform CLI
claude mcp add --env NOTION_TOKEN=<NOTION_TOKEN> --env NOTION_ROOT_PAGE_ID=<NOTION_ROOT_PAGE_ID> --transport stdio easy-notion -- npx -y easy-notion-mcpReplace <…> with your own values
Platform CLI
codex mcp add easy-notion --env NOTION_TOKEN=<NOTION_TOKEN> --env NOTION_ROOT_PAGE_ID=<NOTION_ROOT_PAGE_ID> -- npx -y easy-notion-mcpReplace <…> with your own values
Config file
{
"mcpServers": {
"easy-notion": {
"command": "npx",
"args": [
"-y",
"easy-notion-mcp"
],
"env": {
"NOTION_TOKEN": "<NOTION_TOKEN>",
"NOTION_ROOT_PAGE_ID": "<NOTION_ROOT_PAGE_ID>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"easy-notion": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"easy-notion-mcp"
],
"env": {
"NOTION_TOKEN": "<NOTION_TOKEN>",
"NOTION_ROOT_PAGE_ID": "<NOTION_ROOT_PAGE_ID>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e NOTION_TOKEN=<NOTION_TOKEN> -e NOTION_ROOT_PAGE_ID=<NOTION_ROOT_PAGE_ID> easy-notion npx -y easy-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 easy-notion
How do I install easy-notion in Claude Code?
Run claude mcp add easy-notion -e NOTION_TOKEN=<NOTION_TOKEN> -- npx -y easy-notion-mcp. Use your own Notion integration token and share the pages with that integration first.
What does easy-notion do?
It connects an agent to Notion: markdown goes in and becomes Notion blocks, pages come back as markdown. It offers 43 tools across 24 block types.
How is easy-notion different from the official Notion MCP server?
The official server returns raw block JSON, while easy-notion returns standard markdown. Page reads therefore cost fewer tokens, and the agent does not have to rebuild blocks itself.
