Notion MCP Server

[!NOTE]

We’ve introduced Notion MCP, a remote MCP server with the following improvements:

• Easy installation via standard OAuth. No need to fiddle with JSON or API tokens anymore.
• Powerful tools tailored to AI agents, including editing pages in Markdown. These tools are designed with optimized token consumption in mind.

Learn more and get started at Notion MCP documentation.

We are prioritizing, and only providing active support for, Notion MCP (remote). As a result:

• We may sunset this local MCP server repository in the future.
• Issues and pull requests here are not actively monitored.
• Please do not file issues relating to the remote MCP here; instead, contact Notion support.

This project implements an MCP server for the Notion API.

---

⚠️ Version 2.0.0 breaking changes

Version 2.0.0 migrates to the Notion API 2025-09-03 which introduces data sources as the primary abstraction for databases.

What changed

Removed tools (3):

• post-database-query - replaced by query-data-source
• update-a-database - replaced by update-a-data-source
• create-a-database - replaced by create-a-data-source

New tools (7):

• query-data-source - Query a data source (database) with filters and sorts
• retrieve-a-data-source - Get metadata and schema for a data source
• update-a-data-source - Update data source properties
• create-a-data-source - Create a new data source
• list-data-source-templates - List available templates in a data source
• move-page - Move a page to a different parent location
• retrieve-a-database - Get database metadata including its data source IDs

Parameter changes:

• All database operations now use data_source_id instead of database_id
• Search filter values changed from ["page", "database"] to ["page", "data_source"]
• Page creation now supports both page_id and database_id parents (for data sources)

Do I need to migrate?

No code changes required. MCP tools are discovered automatically when the server starts. When you upgrade to v2.0.0, AI clients will automatically see the new tool names and parameters. The old database tools are no longer available.

If you have hardcoded tool names or prompts that reference the old database tools, update them to use the new data source tools:

Old Tool (v1.x)	New Tool (v2.0)	Parameter Change
post-database-query	query-data-source	database_id → data_source_id
update-a-database	update-a-data-source	database_id → data_source_id
create-a-database	create-a-data-source	No change (uses parent.page_id)

Note: retrieve-a-database is still available and returns database metadata including the list of data source IDs. Use retrieve-a-data-source to get the schema and properties of a specific data source.

Total tools now: 22 (was 19 in v1.x)

---

Page content as Markdown

The server exposes two tools for working with page content as enhanced Markdown instead of block JSON, which is significantly more token-efficient for AI agents:

• retrieve-page-markdown — Read a page's full content as Markdown (GET /v1/pages/{page_id}/markdown). Pass include_transcript: true to inline meeting-note transcripts.
• update-page-markdown — Edit a page's content with Markdown (PATCH /v1/pages/{page_id}/markdown). Prefer replace_content to overwrite the whole page, or update_content for targeted find-and-replace edits.

These endpoints require Notion API version 2026-03-11. The server now sources the Notion-Version he