@notionhq/notion-mcp-server weekly downloads statistics

Notion MCP Server

[!NOTE]

For the best experience, use Remote Notion MCP, our official hosted MCP server. This repository is a separate, self-hosted MCP server implementation that is no longer actively maintained or supported. Please use Remote Notion MCP instead. It is purpose-built to give AI agents faster results using far fewer tokens.

Remote Notion MCP can search your workspace and connected apps semantically, read and edit pages in Markdown, and return only the most relevant context. That means less time waiting, less context-window usage, and lower token costs. It also uses OAuth and automatically respects each user's existing Notion permissions—without API tokens, JSON configuration, manual page sharing, or a local server to maintain.

Feature	Remote Notion MCP	This project (local)
Fast, hosted experience	✅	Runs and updates locally
Token-efficient responses	✅	Limited
Powerful tools tailored for AI agents	✅	Basic API-derived tools
Semantic search across your Notion workspace	✅	Keyword search only
AI Connector search across connected apps	✅	Not available
Markdown-native page reading and editing	✅	Limited to two page-content tools
Seamless OAuth setup	✅	Manual token and JSON configuration
Respects each user's existing Notion permissions	✅	Manual integration permissions and page sharing
Active support and ongoing improvements	✅	Not actively supported

Learn more and get started in the Remote Notion MCP documentation.

We are prioritizing, and only providing active support for, Remote Notion MCP. 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 header per operation from the OpenAPI spec, so these tools use 2026-03-11 while the rest of the API continues to use 2025-09-03 — no configuration needed. If you set Notion-Version yourself via OPENAPI_MCP_HEADERS, your value takes precedence for every tool.

---

Installation

1. Setting up integration in Notion

Go to https://www.notion.so/profile/integrations and create a new internal integration or select an existing one.

…