# Notion MCP Server (self-hosted) [Official] [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/makenotion/notion-mcp-server  
**GitHub Stars:** 4705  
**npm Downloads (last month):** 977867  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/notion-mcp-server-self-hosted

## Description
Notion's official self-hosted MCP server for the Notion API. Runs locally with npx -y @notionhq/notion-mcp-server and a NOTION_TOKEN integration token to search, read and edit pages and data sources. Notion now recommends its hosted Notion MCP and no longer actively maintains this one.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "notion-mcp-server-self-hosted": {
    "command": "npx",
    "args": ["-y","@notionhq/notion-mcp-server"],
    "env": {
      "NOTION_TOKEN": "",
      "OPENAPI_MCP_HEADERS": ""
    }
  }
}
```

**Requires environment variables:** `NOTION_TOKEN`, `OPENAPI_MCP_HEADERS` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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:

```json
{
  "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.

_Full upstream README: https://allmcps.com/mcp/notion-mcp-server-self-hosted/readme_