Notion MCP Server

What is Notion MCP Server?

A Model Context Protocol server that gives AI clients (Claude, Cursor, VS Code, etc.) full read/write access to Notion using a personal access token. Designed for agents, automation, CI, and self-hosted deployments where OAuth-based authentication is impractical.

How to use Notion MCP Server?

Obtain a Notion Personal Access Token (PAT) from the developer portal. Add the server to your MCP client by running npx -y notion-mcp-server (or using Docker) with the NOTION_TOKEN environment variable set. No per-page sharing is required.

Key features of Notion MCP Server

• Two MCP tools (422 tokens) vs. 24 tools (17,163 tokens) from the official server
• 43 operations covering pages, databases, blocks, comments, files, templates, and more
• Batched mutations with atomic rollback, idempotency keys, and rate-limit handling
• Full markdown round-trip for pages, blocks, and comments
• Self-healing validation errors that let the model correct bad payloads in one turn
• Slim, token-efficient response shapes with optional verbose mode

Use cases of Notion MCP Server

• Query, create, and update pages and databases in natural language
• Batch-rename hundreds of pages with idempotent parallel calls
• Apply Notion templates and fill them with content
• Upload diagrams and files to existing Notion pages
• Automate meeting notes, summaries, and comments in CI or background agents

FAQ from Notion MCP Server

What makes this server different from Notion’s official MCP options?

It uses token-based authentication (no OAuth), so it works headless in CI/automation. It loads only 422 tool tokens vs. 17,163 from the official open-source server, and offers batched mutations, idempotency, rate-limit handling, and markdown round-trip. The official hosted MCP is OAuth-only and designed for interactive chat.

What transports does it support?

The server supports both stdio and Streamable HTTP transports. The stdio transport is used with Docker (requires the -i flag) and is the default for CLI-based clients.

How do I authenticate?

Use a Notion Personal Access Token (PAT) obtained from the developer portal. Alternatively, use an Internal Integration token if your admin has disabled PATs. The token is set as the environment variable NOTION_TOKEN.

Does it work headless or in CI?

Yes. Because authentication uses a token rather than OAuth, the server can be run in CI pipelines, cron jobs, background agents, and self-hosted deployments without any user interaction.

Are there any rate limits or token expiration?

The server includes a token-bucket limiter (3 requests per second by default) and exponential backoff that honors Retry-After headers. PATs expire one year after creation; set a reminder to rotate them.