Notion MCP Server

The Notion MCP Server is the official Model Context Protocol (MCP) server published by Notion Labs, Inc. under the MIT license. It bridges AI agents and clients like Claude Desktop, Cursor, Zed, and GitHub Copilot CLI to the full Notion API, enabling them to search, read, create, and edit pages, databases, and comments. The repository is written in TypeScript and is actively maintained on GitHub, with version 2.1.0 released in January 2026.

What It Is

The Notion MCP Server implements the Model Context Protocol specification on top of the Notion REST API. It exposes a set of tools that AI agents can call to interact with a connected Notion workspace — searching for pages, querying data sources (databases), creating and updating content, and posting comments. The server runs locally via npx or Docker, or can be deployed as a remote MCP server using Notion's hosted OAuth-based offering documented at developers.notion.com/docs/mcp.

Update: v2.1.0 and the v2.0.0 Breaking Changes

The latest release is v2.1.0 (published 2026-01-31). Version 2.0.0 was a significant breaking release that migrated to the Notion API version 2025-09-03, which introduced data sources as the primary abstraction for databases. Key changes in v2.0.0:

• Removed tools (3): post-database-query, update-a-database, create-a-database
• New tools (7): query-data-source, retrieve-a-data-source, update-a-data-source, create-a-data-source, list-data-source-templates, move-page, retrieve-a-database
• All database operations now use data_source_id instead of database_id
• Total tool count is now 22 (up from 19 in v1.x)

The README also notes that Notion is prioritizing the remote MCP server (with OAuth) and may sunset this local repository in the future.

Page Content as Markdown

A standout feature introduced in recent versions is the ability to read and write Notion page content as enhanced Markdown rather than raw block JSON. This is described as significantly more token-efficient for AI agents:

• retrieve-page-markdown — reads a full page as Markdown, with optional meeting-note transcript inlining
• update-page-markdown — edits page content using Markdown, supporting full replacement or targeted find-and-replace

These endpoints require Notion API version 2026-03-11 and the server automatically selects the correct API version per operation from the OpenAPI spec.

Transport and Deployment Options

The server supports two transport modes:

• STDIO (default): Standard input/output, compatible with Claude Desktop, Cursor, and most MCP clients
• Streamable HTTP: For web-based applications; runs on a configurable port with bearer token authentication, DNS rebinding protection, and optional per-request token passthrough for multi-tenant deployments

Installation options include npx, Docker Hub official image (mcp/notion), or building locally. Configuration is done via a JSON snippet added to the MCP client's config file, with NOTION_TOKEN as the recommended authentication method.

Setup Path

1. Create an internal Notion integration at notion.so/profile/integrations and copy the token
2. Grant the integration access to relevant pages or databases via the Access tab
3. Add the MCP server config to your client (Cursor, Claude Desktop, Zed, or GitHub Copilot CLI) using npx @notionhq/notion-mcp-server with the NOTION_TOKEN environment variable
4. Optionally use Docker for a more isolated deployment

The README notes that security-conscious users can create read-only integration tokens by limiting capabilities to "Read content" only in the integration settings.