MCP Server
Notion MCP Server
Official Notion MCP server providing AI assistants with read-write access to Notion workspaces through markdown-based page operations and data source queries
What is Notion MCP Server?
The Notion MCP Server is an official implementation maintained by Notion that exposes workspace data through the Model Context Protocol. This server implements the Notion API version 2025-09-03, introducing data sources as the primary abstraction for database interactions alongside traditional page operations. The server provides 22 distinct tools for managing pages, databases (data sources), comments, users, and search operations, with specialized markdown endpoints that significantly reduce token consumption compared to block JSON formats. Version 2.0 introduced retrieve-page-markdown and update-page-markdown tools that leverage the Notion-Version 2026-03-11 header for efficient content operations. Authentication requires an internal Notion integration token with configurable capabilities, and workspace administrators must explicitly grant page-level access to the integration. The server supports both NPM-based deployment via npx and Docker containers, with environment variable configuration for integration tokens and API versioning.
Key capabilities
Markdown-Based Page Operations with Token Efficiency
Exposes retrieve-page-markdown and update-page-markdown tools using Notion API 2026-03-11 version header, enabling AI agents to read and write page content in markdown format instead of verbose block JSON, dramatically reducing token consumption.
Data Source Abstraction for Database Operations
Implements Notion API 2025-09-03 data source model through query-data-source, retrieve-a-data-source, update-a-data-source, and create-a-data-source tools, replacing legacy database endpoints with a unified abstraction for structured data queries.
Integration Token Authentication with Granular Capabilities
Requires internal Notion integration tokens configured via NOTION_TOKEN environment variable or OPENAPI_MCP_HEADERS JSON object, with workspace admins controlling read/write capabilities and page-level access through Notion's integration management interface.
Per-Operation API Version Sourcing from OpenAPI Spec
Automatically selects appropriate Notion-Version headers per tool based on OpenAPI specification, allowing markdown endpoints to use 2026-03-11 while data source tools use 2025-09-03, with optional override via OPENAPI_MCP_HEADERS environment variable.
Use cases
Knowledge Base Queries with Data Source Filtering
AI assistants can search Notion databases using query-data-source with filter objects and sort parameters, retrieving structured data from project trackers, documentation databases, and knowledge repositories without manually parsing block structures.
Content Authoring with Markdown Workflows
Enables AI tools to draft, edit, and publish Notion pages using markdown syntax through update-page-markdown, supporting both replace_content for full rewrites and update_content for targeted find-and-replace operations on existing pages.
Read-Only Integration for Security-Conscious Workspaces
Organizations can configure integration capabilities to grant only 'Read content' permission, creating a read-only MCP server that allows AI assistants to search and retrieve information without modification risk to workspace data.
Multi-Client Workspace Access Across Development Tools
Developers can configure the same integration token across Cursor, Claude Desktop, Zed, and GitHub Copilot CLI using consistent environment variable patterns, enabling unified Notion access across different AI coding environments.
MCP capabilities
Tools
Search workspace
Retrieve page as Markdown
Create and update pages
Manage data sources
Connection and auth
- Notion internal integration token with org:read, page:read, page:write permissions
- Workspace administrator approval for integration access
- Page-level connections configured in Notion workspace
- NOTION_TOKEN environment variable or OPENAPI_MCP_HEADERS with Bearer auth
Client configuration
Claude Desktop
{
"command": "npx",
"args": [
"-y",
"@notionhq/notion-mcp-server"
],
"env": {
"NOTION_TOKEN": "YOUR_INTEGRATION_TOKEN"
}
}