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-sourceupdate-a-database - replaced by update-a-data-sourcecreate-a-database - replaced by create-a-data-source
New tools (7):
query-data-source - Query a data source (database) with filters and sortsretrieve-a-data-source - Get metadata and schema for a data sourceupdate-a-data-source - Update data source propertiescreate-a-data-source - Create a new data sourcelist-data-source-templates - List available templates in a data sourcemove-page - Move a page to a different parent locationretrieve-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.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
