awkoy/notion-mcp-server

Give your AI read/write access to Notion with one token and one command. Claude Code, Claude Desktop, Cursor, VS Code, Cline, Zed, anything that speaks MCP: it can create pages, query databases, append blocks, apply templates, comment and upload files, in plain language.
Notion ships its own MCP server. Where this one differs:
- **It authenticates with a token, so it runs headless.** Notion's hosted MCP is OAuth-only and someone has to click "Authorize". This one works in CI, cron jobs, background agents and self-hosted deployments.
- **It doesn't spend your context on tool schemas.** The official open-source server loads 24 endpoint schemas into the model's context at connection: 17,163 tokens, re-sent with every request for the rest of the session. This one loads three tools, 1,005 tokens — 94% less, 17× smaller — and fetches an operation's schema only when a task actually touches it.
- **It doesn't spend your context on answers either.** Reading the same pages through both servers, pulling a page's content costs **82% less** (26,071 → 4,568 tokens on an 88-block page), a 25-row database query **81% less**, a page object **68% less**. Notion's raw JSON is mostly id/type wrappers, annotations, and created_by/parent/icon blocks, and none of it reaches the model. That is the half that compounds, because a tool surface is paid once and responses are paid on every call. Measured against a reproducible fixture, with the caveats stated →
Nothing is lost to get there: a database query returns flat name → value rows instead of Notion's raw properties bags (5.3× lighter in the benchmark), and verbose: true gives you the untouched SDK shape whenever you want it — within 4 tokens of what the official server returns, which is how the benchmark proves both are reading the same thing. Batched mutations with atomic rollback, idempotency keys, retry on rate limits and self-healing validation errors are built in, and the comparison below has the rest.
Quick start
**1. Get a Notion token.** Open **app.notion.com/developers/tokens** → **+ New token** → name it, pick your workspace → **Create token** → copy the ntn_… value. A Personal Access Token sees everything *you* can see, with no per-page sharing. (Page missing or empty? Your admin disabled PATs — see auth alternatives.)
**2. Install it.**
add-mcp finds the MCP clients on your machine and writes the config for the ones you pick: Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Cline, Windsurf, Zed and a dozen others. Add -g to install at user level instead of the current project, -a claude-code to skip the picker, --all to write every client at once.
> Keep the --env flag. Without it the entry is written without a token, and the server starts and then fails every call with an auth error.
Or install it by hand: JSON config, Claude Code, Cursor, VS Code, Gemini CLI, Claude Desktop, Docker
**Any client that reads an mcpServers block** (Cursor's ~/.cursor/mcp.json, Claude Desktop's claude_desktop_config.json, Cline's settings, Zed, Continue…):
**Claude Code:**
Claude Code speaks the 2025-era protocol over stdio unless told otherwise. Set MCP_PROTOCOL_NEGOTIATION=auto in its environment and it probes for MCP 2026-07-28 (stateless requests, cache hints on every list). The server serves both.
**Cursor:** — click, then replace YOUR_NOTION_TOKEN in the generated entry.
**VS Code (Copilot agent mode):** %22%2C%22password%22%3Atrue%7D%5D&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22notion-mcp-server%22%5D%2C%22env%22%3A%7B%22NOTION_TOKEN%22%3A%22%24%7Binput%3Anotion_token%7D%22%7D%7D) — VS Code prompts for the token and stores it as a secret input.
**Gemini CLI:**
The repo ships a gemini-extension.json, so this installs as an extension: it asks for the token once, keeps it in your system keychain, and starts the server with npx.
**Claude Desktop, without Node.js:** download notion-mcp-server.mcpb from the latest release and double-click it (or drag it into Settings → Extensions), then paste your token when prompted. Never edited a config file before? The step-by-step walkthrough assumes nothing.
**Docker / Podman / OrbStack:**
The -i flag is required for stdio. The image is OCI-compliant, so Podman, OrbStack, colima, Rancher Desktop, Finch and nerdctl take the same flags. For a long-running HTTP container see Remote / HTTP transport.
**3. Try it.** In a new chat:
> *"Use Notion to make a page called 'Hello from my agent' and add a checklist of three things to try today."*