SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI developer platformsnotion-mcp-server

notion-mcp-server

Notion official MCP server

Open website

About this tool

Purpose

Notion MCP Server is Notion's official Model Context Protocol (MCP) server implementation, used to connect the Notion API to AI clients that support MCP, enabling AI to search, read, and edit pages and database content in Notion.

In this repository, the official statement explicitly states: This repository is a standalone self-hosted MCP server implementation and is no longer actively maintained or supported. It is recommended to switch to the officially hosted Remote Notion MCP. Going forward, the official team will only provide active support for Remote Notion MCP, and may discontinue this self-hosted repository in the future; issues and pull requests here will also not be actively monitored.

Main Capabilities

  • Exposes Notion API capabilities through MCP, currently with 22 tools in total (19 in v1.x).
  • Version 2.0.0 migrates to Notion API 2025-09-03 and introduces data source as the primary abstraction for databases.
  • Removed three tools: post-database-query, update-a-database, and create-a-database, which are replaced by query-data-source, update-a-data-source, and create-a-data-source respectively.
  • Data source-related tools include: query-data-source (query a data source/database by filters and sorts), retrieve-a-data-source (retrieve data source metadata and schema), update-a-data-source (update data source properties), create-a-data-source (create a new data source), list-data-source-templates (list templates available in a data source).
  • Also provides move-page (move a page to a different parent location), retrieve-a-database (retrieve database metadata, including its list of data source IDs).
  • Parameter changes: all database operations now use data_source_id instead of database_id; search filter values change from ["page", "database"] to ["page", "data_source"]; creating a page now supports both page_id and database_id as parent (for data sources).
  • Page content is exposed as enhanced Markdown instead of block JSON, which the official team says is significantly more token-efficient for AI agents: retrieve-page-markdown (read the full page content as Markdown, GET /v1/pages/{page_id}/markdown, pass include_transcript: true to inline meeting note transcriptions), update-page-markdown (edit page content as Markdown, PATCH /v1/pages/{page_id}/markdown, use replace_content to overwrite the entire page, or use update_content for targeted find-and-replace).
  • The above Markdown endpoints require Notion API version 2026-03-11; the server reads the Notion-Version header from the OpenAPI specification on a per-operation basis, so these tools use 2026-03-11, while the rest of the API continues to use 2025-09-03, with no manual configuration required. If Notion-Version is set manually via OPENAPI_MCP_HEADERS, that value takes precedence for all tools.

Usage

The official configuration points are as follows:

  • In the https://www.notion.so/profile/integrations Create a new internal integration or select an existing one. The official notice states that although the scope exposed by the Notion API is limited (for example, databases cannot be deleted through MCP), exposing workspace data to an LLM still carries non-zero risk. Security-conscious users can further configure the integration's Capabilities, for example granting only "Read content" to create a read-only token.
  • Ensure that the relevant pages and databases are connected to the integration: you can edit access permissions and select pages on the Access tab of the internal integration settings; you can also click the three-dot menu on the target page and select "Connect to integration" to grant page access one by one.
  • Add the configuration to .cursor/mcp.json or claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json), or add it to settings.json.
  • You can use the Copilot CLI to interactively add an MCP server, or create or edit the configuration file ~/.copilot/mcp-config.json and write the configuration into it.
  • There are two options for running Docker: when using the official Docker Hub image, it can be configured through NOTION_TOKEN (recommended) or OPENAPI_MCP_HEADERS (advanced usage).
  • You can also build and run the Docker image locally, and then write the corresponding client configuration.
  • You need to replace ntn_**** in the example with your integration secret, which can be found on the integration configuration tab.

Transport modes

  • The default transport mode uses standard input/output (stdio), which is the standard MCP transport used by most clients (such as Claude Desktop).
  • For web-based applications or clients that prefer HTTP communication, the Streamable HTTP transport can be used; by default, the server is located at http://127.0.0.1:<port>/mcp.
  • The Streamable HTTP transport requires bearer token authentication, and there are three options: the server generates a secure random token and writes it to a file with restricted permissions; the command-line argument --auth-token takes precedence over the AUTH_TOKEN environment variable.
  • Bearer token authentication can be disabled only when the insecure flag --unsafe-disable-auth is explicitly used. The official warning states that this flag is insecure, and the server may be reachable to the pages you access due to DNS rebinding, so it should only be used on an isolated network. When authentication is disabled, the server enables DNS rebinding protection by checking the Host and Origin headers against the configured localhost and loopback hosts; the old --disable-auth flag is still accepted as a deprecated alias, but prints a warning.
  • All requests to the Streamable HTTP transport must include the bearer token in the Authorization header.
  • When using either transport mode, you need to set NOTION_TOKEN (recommended) or the OPENAPI_MCP_HEADERS environment variable with the Notion integration token.

Token passthrough

By default, the server authenticates to Notion with a single built-in token at startup, thereby locking one deployment to a single Notion integration. To serve multiple integrations from one deployment, you can enable token passthrough, allowing each client to provide its own Notion integration token per connection: the client sends its Notion token in the initialize request using the dedicated Notion-Token header. The token resolution order for each connection is: the Notion-Token header (preferred, explicit and unambiguous, and can coexist with the server's own Authorization gateway authentication; if present, it must be a valid Notion token, otherwise the request is rejected with 401); Authorization: Bearer ntn_**** (only when the server's own bearer authentication is disabled, that is, --unsafe-disable-auth, can this header freely carry a Notion token); otherwise, the startup environment token is used (NOTION_TOKEN / OPENAPI_MCP_HEADERS, if set), so passthrough and the default integration can coexist in the same deployment. Only with Only values with a Notion token prefix (ntn_, or the legacy secret_) are treated as Notion tokens, so server gateway keys and a tenant's Notion token will not conflict. Each token is bound to its MCP session; tokens are never logged (only a redacted prefix is output). The official guidance states that this is a deliberate token passthrough setup, that it should always be deployed over TLS, and that the server's own bearer authentication (--auth-token) should preferably be retained as a gateway in front of multi-tenant traffic.

Local testing

The official local testing method is as follows: run npm link in the repository root to create a machine-global symlink pointing to the notion-mcp-server package; merge the configuration snippet into Cursor's mcp.json (or another MCP client to be tested); when done, run npm unlink in the repository root to clean up.

Use cases

Suitable for workflows that use MCP to let AI clients access, retrieve, and edit Notion pages and databases, such as querying databases, commenting, and creating pages in natural language. The official examples state that with specific instructions, the AI will correctly plan two API calls (v1/search and v1/comments) to complete the task; similarly, another instruction will add a page named "Notion MCP" under the parent page "Development". Content IDs can also be referenced directly.

Limitations

  • The repository is a self-hosted implementation, and the official maintainers state that it is no longer actively maintained or supported, may be discontinued in the future, and issues and PRs are not actively monitored; remote MCP-related questions should not be submitted here and should be directed to Notion support.
  • Upgrading to v2.0.0 requires no code changes; MCP tools are automatically discovered when the server starts, and AI clients will automatically see the new tool names and parameters, but the old database tools are no longer available; if old database tool names or prompts are hardcoded, they need to be updated to the new data source tools.
  • retrieve-a-database is still available and returns database metadata and a list of data source IDs; to get the schema and properties of a specific data source, use retrieve-a-data-source.
  • The Markdown page tools depend on Notion API version 2026-03-11, while the rest of the API uses 2025-09-03.
  • The official materials do not provide specificpricing and cost information, so none is provided for now.

Related tools

Browse category