Notion MCP Server (Official)

What is Notion MCP Server (Official)?

Notion MCP Server (Official) is Notion's open-source, self-hosted notion mcp server (@notionhq/notion-mcp-server). It turns the Notion API into MCP tools so AI clients can search, read, create and update pages, databases, comments and blocks.

Notion now marks this repository as no longer actively maintained and recommends its hosted Remote Notion MCP at https://mcp.notion.com/mcp instead. This page covers both: the local server this listing describes, and the hosted endpoint Notion points users to.

How to use Notion MCP Server (Official)?

Pick one of two setups:

• Remote Notion MCP (recommended by Notion): no install. You add https://mcp.notion.com/mcp to your client and sign in with OAuth. It uses your existing Notion permissions.
• Local server (this repository): runs with npx or Docker. It authenticates with an internal integration token (ntn_...), and you share pages with that integration yourself.

Local setup: token and page access

1. Go to https://www.notion.so/profile/integrations and create an internal integration.
2. In the integration's Access tab, choose the pages and databases it may use. You can also open a page, click the three dots and choose Connect to integration.
3. Copy the integration secret. For a read-only setup, turn on only "Read content" under Capabilities.

Claude Desktop

Add the server to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["-y", "@notionhq/notion-mcp-server"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

Docker users can run the official mcp/notion image instead (see the README).

Cursor

For the local server, put the same JSON in .cursor/mcp.json. For the hosted server, use:

{
  "mcpServers": {
    "notion": {
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Then open Customize in Cursor's sidebar, enable Notion and complete the OAuth flow.

Claude Code

Notion documents the hosted endpoint for Claude Code:

claude mcp add --transport http notion https://mcp.notion.com/mcp

Then run /mcp in Claude Code and follow the OAuth flow.

VS Code

Create .vscode/mcp.json:

{
  "servers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    }
  }
}

Run MCP: List Servers from the Command Palette, start Notion and sign in.

Codex

Add this to ~/.codex/config.toml, then run codex mcp login notion:

[mcp_servers.notion]
url = "https://mcp.notion.com/mcp"

The local server's README also has configs for Zed and the GitHub Copilot CLI (~/.copilot/mcp-config.json).

Key features of Notion MCP Server (Official)

• Published by Notion (makenotion) under the MIT license, on npm as @notionhq/notion-mcp-server and on Docker Hub as mcp/notion.
• Tools are generated from Notion's OpenAPI spec, so each tool matches one Notion API endpoint.
• Version 2.0 uses Notion API 2025-09-03 and its data sources model (data_source_id instead of database_id).
• Page content can be read and edited as Markdown. This uses far fewer tokens than block JSON.
• STDIO transport by default. Streamable HTTP is available with --transport http, which requires a bearer token (--auth-token or AUTH_TOKEN).
• --enable-token-passthrough lets one HTTP deployment serve several integrations through a per-session Notion-Token header.
• Some actions are left out on purpose. For example, you cannot delete databases through it.

Notion MCP Server (Official) tools

The local server's tools fall into a few groups:

• Search and users: post-search searches pages and data sources. get-users, get-user and get-self look up workspace members and the bot user.
• Pages: post-page, retrieve-a-page, patch-page, retrieve-a-page-property and move-page create, read, update and move pages.
• Markdown content: retrieve-page-markdown and update-page-markdown read and edit a whole page as Markdown.
• Blocks: get-block-children, patch-block-children, retrieve-a-block, update-a-block and delete-a-block work with page content block by block.
• Databases and data sources: query-data-source (filters and sorts), retrieve-a-data-source, create-a-data-source, update-a-data-source, list-data-source-templates and retrieve-a-database.
• Comments: create-a-comment and retrieve-a-comment.

The hosted Remote Notion MCP has a different, agent-oriented set of tools, such as notion-search, notion-fetch, notion-create-pages, notion-update-page and notion-query-data-sources.

Use cases of Notion MCP Server (Official)

• Commenting on pages from chat: "Comment 'Hello MCP' on page 'Getting started'". The client calls search, then the comments endpoint.
• Creating pages under a parent: "Add a page titled 'Notion MCP' to page 'Development'".
• Reading a page by ID for context while coding: "Get the content of page 1a6b35e6e67f802fa7e1d27686f017f2".
• Querying a task or bug database with filters and sorts, then summarizing the results.
• Rewriting meeting notes or specs through the Markdown tools, without handling block JSON.

Notion MCP Server (Official) vs alternatives

• Remote Notion MCP (hosted): Notion's recommended mcp notion option. It uses OAuth and your own permissions, has semantic search across Notion and connected apps, and is actively supported. It needs no local process. Some features, such as AI search and MCP tokens for headless use, depend on a Business or Enterprise plan.
• This local server: useful when you need token-based, headless access or want to self-host. Notion says it gets no active support and may be sunset.
• Community servers: for example awkoy/notion-mcp-server, an unofficial project published on npm as notion-mcp-server. It is a separate codebase, not Notion's.

Troubleshooting Notion MCP Server (Official)

• A page or database is not found: the integration can only see content shared with it. Add the page in the integration's Access tab or with Connect to integration.
• Old database tools are missing: v2.0 replaced post-database-query, update-a-database and create-a-database with query-data-source, update-a-data-source and create-a-data-source. Update any prompts that hardcode the old names.
• HTTP requests are rejected: Streamable HTTP needs Authorization: Bearer <token> on every request. Without --auth-token, the server writes a generated token to a temp file. Avoid --unsafe-disable-auth except on an isolated network.
• Your client only supports local servers: you can still reach the hosted server through the mcp-remote bridge: "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.notion.com/mcp"].
• Hosted OAuth fails: disconnect and reconnect the client, then check your access in the target workspace. Workspace guests cannot connect.