notion-mcp-server
installs/mo · npmstarsforks
How to install notion-mcp-server?
makenotion/notion-mcp-server
$git clone https://github.com/makenotion/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
README.md
| 1 | # Notion MCP Server |
| 2 | |
| 3 | > [!NOTE] |
| 4 | > |
| 5 | > We’ve introduced **Notion MCP**, a remote MCP server with the following improvements: |
| 6 | > |
| 7 | > - Easy installation via standard OAuth. No need to fiddle with JSON or API tokens anymore. |
| 8 | > - Powerful tools tailored to AI agents, including editing pages in Markdown. These tools are designed with optimized token consumption in mind. |
| 9 | > |
| 10 | > Learn more and get started at [Notion MCP documentation](https://developers.notion.com/docs/mcp). |
| 11 | > |
| 12 | > We are prioritizing, and only providing active support for, **Notion MCP** (remote). As a result: |
| 13 | > |
| 14 | > - We may sunset this local MCP server repository in the future. |
| 15 | > - Issues and pull requests here are not actively monitored. |
| 16 | > - Please do not file issues relating to the remote MCP here; instead, contact Notion support. |
| 17 | |
| 18 |  |
| 19 | |
| 20 | This project implements an [MCP server](https://spec.modelcontextprotocol.io/) for the [Notion API](https://developers.notion.com/reference/intro). |
| 21 | |
| 22 |  |
| 23 | |
| 24 | --- |
| 25 | |
| 26 | ## ⚠️ Version 2.0.0 breaking changes |
| 27 | |
| 28 | **Version 2.0.0 migrates to the Notion API 2025-09-03** which introduces data sources as the primary abstraction for databases. |
| 29 | |
| 30 | ### What changed |
| 31 | |
| 32 | **Removed tools (3):** |
| 33 | |
| 34 | - `post-database-query` - replaced by `query-data-source` |
| 35 | - `update-a-database` - replaced by `update-a-data-source` |
| 36 | - `create-a-database` - replaced by `create-a-data-source` |
| 37 | |
| 38 | **New tools (7):** |
| 39 | |
| 40 | - `query-data-source` - Query a data source (database) with filters and sorts |
| 41 | - `retrieve-a-data-source` - Get metadata and schema for a data source |
| 42 | - `update-a-data-source` - Update data source properties |
| 43 | - `create-a-data-source` - Create a new data source |
| 44 | - `list-data-source-templates` - List available templates in a data source |
| 45 | - `move-page` - Move a page to a different parent location |
| 46 | - `retrieve-a-database` - Get database metadata including its data source IDs |
| 47 | |
| 48 | **Parameter changes:** |
| 49 | |
| 50 | - All database operations now use `data_source_id` instead of `database_id` |
| 51 | - Search filter values changed from `["page", "database"]` to `["page", "data_source"]` |
| 52 | - Page creation now supports both `page_id` and `database_id` parents (for data sources) |
| 53 | |
| 54 | ### Do I need to migrate? |
| 55 | |
| 56 | **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. |
| 57 | |
| 58 | If you have hardcoded tool names or prompts that reference the old database tools, update them to use the new data source tools: |
| 59 | |
| 60 | | Old Tool (v1.x) | New Tool (v2.0) | Parameter Change | |
| 61 | | -------------- | --------------- | ---------------- | |
| 62 | | `post-database-query` | `query-data-source` | `database_id` → `data_source_id` | |
| 63 | | `update-a-database` | `update-a-data-source` | `database_id` → `data_source_id` | |
| 64 | | `create-a-database` | `create-a-data-source` | No change (uses `parent.page_id`) | |
| 65 | |
| 66 | > **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. |
| 67 | |
| 68 | **Total tools now: 22** (was 19 in v1.x) |
| 69 | |
| 70 | --- |
| 71 | |
| 72 | ## Page content as Markdown |
| 73 | |
| 74 | 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: |
| 75 | |
| 76 | - `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. |
| 77 | - `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. |
| 78 | |
| 79 | These endpoints require Notion API version `2026-03-11`. The server now sources the `Notion-Version` he |
People who liked this also viewed
6 picksType
- fastmcp🚀 The fast, Pythonic way to build MCP servers and clients.MCP ServersJul 2026
- playwright-mcpPlaywright MCP serverMCP ServersJul 2026
- ext-appsOfficial repo for spec & SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP serversMCP ServersJul 2026
- langchain-mcp-adaptersLangChain 🔌 MCPMCP ServersJul 2026
- mcporterCall MCPs via TypeScript, masquerading as simple TypeScript API. Or package them as cli.MCP ServersJul 2026
- mcp-proxyA bridge between Streamable HTTP and stdio MCP transportsMCP ServersJul 2026
