makenotion/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.