Notion MCP Server
@awkoy
About Notion MCP Server
Notion MCP server for Claude, Cursor, ChatGPT & Claude Desktop. Connect AI agents to Notion via Model Context Protocol — pages, databases, blocks, comments, files.
Config
Add this server to your MCP-compatible client using the configuration below.
{
"mcpServers": {
"notion-mcp-server": {
"command": "npx",
"args": [
"-y",
"notion-mcp-server"
],
"env": {
"NOTION_TOKEN": "YOUR_KEY",
"NOTION_PAGE_ID": "YOUR_PAGE_ID"
}
}
}
}Tools
5Perform various page operations (create, archive, restore, search, update)
Perform various block operations (retrieve, update, delete, append children, batch operations)
Perform various database operations (create, query, update)
Perform various comment operations (get, add to page, add to discussion)
Perform various user operations (list, get, get bot)
Overview
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.
Frequently asked questions
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.
Basic information
More Memory & Knowledge MCP servers
ctxfile
ctxfileLocal-first MCP server that snapshots your project's working state into one context object. Open-core, privacy-first.
Basic Memory
basicmachines-coAI conversations that actually remember. Never re-explain your project to your AI again. Join our Discord: https://discord.gg/tyvKNccgqN
📓 GistPad MCP
lostintangent📓 An MCP server for managing your personal knowledge, daily notes, and re-usable prompts via GitHub Gists
Solomd
zhitongblogA markdown editor — and the bridge to your LLM. Local-first, MIT, ~15 MB. Bundled MCP server lets Claude Code / Codex / Cursor drive your vault directly. 14 AI providers BYOK.
Anytype MCP Server
anyprotoAn MCP server enabling AI assistants to interact with Anytype - your encrypted, local and collaborative wiki - to organize objects, lists, and more through natural language.
Comments