Notion MCP Server (self Hosted)

What Notion MCP Server (self-hosted) does

Notion MCP Server (self-hosted) exposes Notion API operations to AI clients through the Model Context Protocol. It runs locally and uses a Notion internal integration token to access pages and databases that have been explicitly connected to that integration.

The server supports workspace keyword search, page retrieval and editing, database metadata access, and database operations through Notion's data-source model. Its tool set includes 22 tools in the 2.0 generation, with data sources replacing the older database query, update, and creation tools.

How it works

An MCP client starts the package with npx -y @notionhq/notion-mcp-server. The server sends requests to the Notion API using either NOTION_TOKEN or the more configurable OPENAPI_MCP_HEADERS variable. MCP tools are discovered when the server starts, so clients receive the available tool names and parameters automatically.

Notion access is controlled in two places: the integration's capabilities and the pages or databases connected to it. A read-only integration can be created by granting only content-reading access. Page and database sharing therefore needs to be configured manually in Notion rather than being inherited automatically from each user's account.

Setup and configuration

Create or select an internal integration from Notion's integrations settings, then copy its token. Grant the integration access to the pages and databases the agent should use. Add the server to an MCP client configuration with a local command such as:

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

OPENAPI_MCP_HEADERS can supply an authorization header and an explicit Notion API version for advanced configurations.

Tools and capabilities

• Search Notion content by keyword, with page and data-source filters.
• Retrieve, create, update, and move pages.
• Read page content as enhanced Markdown with retrieve-page-markdown.
• Replace a page's Markdown content or apply targeted find-and-replace edits with update-page-markdown.
• Retrieve database metadata and data-source schemas.
• Query, create, and update data sources, including filters and sorts.
• List templates available in a data source.

The Markdown endpoints support optional meeting-note transcript inclusion. Markdown operations use Notion API version 2026-03-11; other API operations use 2025-09-03 by default. A value supplied through OPENAPI_MCP_HEADERS takes precedence for every tool.

Limitations and notes

This local implementation is no longer actively maintained or supported, and its issues and pull requests are not actively monitored. Notion recommends its hosted Remote Notion MCP instead.

Search is keyword-based rather than semantic, and connected-app search is unavailable. The local server requires manual token handling, page sharing, and JSON configuration. Its Markdown support is limited to the two page-content tools, while responses are described as less token-efficient than the hosted alternative.

Version 2.0 replaces database_id-based query, update, and creation tools with data-source equivalents using data_source_id. Clients discover tools automatically, but prompts or code that hardcode the former tool names need to be updated.