# Notion MCP Server: the self-hosted Notion connector Notion itself no longer supports

> The official Notion MCP server for local use exposes 22 tools over the Notion API, including two Markdown page tools. Notion now points users to its hosted Remote MCP instead, and this repository is no longer actively maintained.

**makenotion/notion-mcp-server** — Official Notion MCP Server

- Repository: https://github.com/makenotion/notion-mcp-server
- Stars: 4,653 · Forks: 634
- Language: TypeScript
- License: MIT
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/makenotion-notion-mcp-server

## What the self-hosted Notion MCP server is for

This project is a local implementation of a Model Context Protocol server for the Notion API, written in TypeScript and published as the npm package @notionhq/notion-mcp-server. It lets an MCP-capable AI client call Notion endpoints as tools: search a workspace, read and edit page content, query and update data sources, and move pages. The audience is engineers who already run an MCP client locally and want the Notion connection to live on their own machine rather than behind a hosted service.

The README is blunt about the project's position. Notion recommends Remote Notion MCP, its hosted server, and states that this repository is a separate, self-hosted implementation that is no longer actively maintained or supported. It adds that issues and pull requests here are not actively monitored and that the repository may be sunset in the future. Anyone evaluating this project should read that notice as part of the product, not as boilerplate. The last push to the repository was on 2026-09-20, so the code is not frozen, but the maintainer's stated support commitment points elsewhere.

## How the server maps Notion endpoints onto MCP tools

The server is generated around the Notion OpenAPI specification. The Dockerfile copies scripts/notion-openapi.json into the runtime image, and the dependencies include openapi-client-axios, openapi-schema-validator and mustache, which is the pattern used to turn OpenAPI operations into callable tools with validated parameters. That is why the tool surface tracks Notion API changes closely and why version bumps can rename tools rather than add them.

Version 2.0.0 is the clearest example. It migrated to Notion API 2025-09-03, which makes data sources the primary abstraction for databases. Three tools were removed (post-database-query, update-a-database, create-a-database) and seven were added, including query-data-source, retrieve-a-data-source, update-a-data-source, create-a-data-source, list-data-source-templates, move-page and retrieve-a-database. Database operations now take data_source_id instead of database_id, and search filters accept page and data_source rather than page and database. The README states that no code changes are required on the client side, because tools are discovered when the server starts, but any hardcoded tool names or prompts must be updated. The total is now 22 tools, up from 19 in v1.x.

Two tools handle page content as Markdown instead of block JSON: retrieve-page-markdown reads a page through GET /v1/pages/{page_id}/markdown, and update-page-markdown edits through PATCH on the same path. The README describes the second as preferring replace_content for a full overwrite or update_content for targeted find-and-replace. These endpoints need Notion API version 2026-03-11, and the server sources the Notion-Version header per operation from the OpenAPI spec, so those two tools use 2026-03-11 while the rest use 2025-09-03. If you set Notion-Version yourself through OPENAPI_MCP_HEADERS, your value wins for every tool. That override is the escape hatch and also the easiest way to break the Markdown tools without noticing.

## Setup: integration token, page access, and client config

Installation has three parts, and skipping the second is the most common cause of empty search results. First, create an internal integration at https://www.notion.so/profile/integrations and copy its token. Second, connect the pages and databases you want the agent to see: either through the Access tab of the integration settings, or per page via the three dots menu and Connect to integration. An integration with no shared pages returns nothing, no matter how the client is configured.

The README also notes that you can narrow the integration's capabilities, for example by granting only Read content, and warns that exposing workspace data to LLMs carries a non-zero risk. For a read-only setup, that capability toggle is the control that matters.

The package ships a binary named notion-mcp-server, and the Dockerfile uses it as the container entrypoint:

```dockerfile
ENV OPENAPI_MCP_HEADERS="{}"

ENTRYPOINT ["notion-mcp-server"]
```

The Dockerfile sets OPENAPI_MCP_HEADERS to an empty object as its default, so the value has to be supplied at run time. The README's client configuration section is where the token is added; the README does not print a complete JSON example in the text available here, so copy the key name exactly as the Dockerfile spells it and confirm the surrounding structure against the README section titled Adding MCP config to your client.

A container path is also provided. docker-compose.yml builds the image, keeps stdin open and a TTY attached, and sets restart: unless-stopped:

```yaml
services:
  notion-mcp-server:
    build: .
    stdin_open: true
    tty: true
    restart: unless-stopped
```

After the client restarts, the tool list should show 22 entries, including query-data-source and retrieve-page-markdown. If you see post-database-query instead, the client is running a v1.x build. The README does not document a rollback path for the v2.0.0 tool rename, so pin the package version if a client depends on the old names.

## Where the local server falls short

The README's own comparison table is the most honest limitation list available. Search here is keyword-based, while Remote Notion MCP searches the workspace semantically and can search connected apps. Responses are described as limited in token efficiency against the hosted server's token-efficient output. Page reading and editing as Markdown is limited to the two page-content tools. Setup requires a manual token and JSON configuration rather than OAuth, and permissions come from manual integration sharing rather than each user's existing Notion permissions.

Two further constraints are worth stating plainly. The integration scope is deliberately narrower than the Notion API: the README gives database deletion as an example of something not exposed through MCP. And because the tool list is derived from an OpenAPI spec, a Notion API change can rename or remove tools in a minor-looking release, as v2.0.0 did. This is the wrong tool if you want a supported integration with a vendor answering your issues, if your team cannot manage tokens and page sharing, or if semantic search over a large workspace is the reason you are connecting Notion to an agent at all.

## Remote Notion MCP versus running this locally

The real alternative is the one Notion names: Remote Notion MCP, its official hosted server. The difference is architectural, not cosmetic. Remote Notion MCP runs as a hosted service reached over OAuth, so there is no token in a JSON file and no local process to keep updated. It respects each user's existing Notion permissions instead of relying on an integration's manual page sharing, which changes who can see what when several people use the same agent. It searches semantically and returns only the most relevant context, while this server issues keyword searches and returns API-shaped responses that consume more of the context window.

Running locally has its own justification. The connection stays on your machine, the server is the open source code in this repository, and you can point it at a self-hosted setup through the Docker image. If your requirement is that no Notion traffic leaves infrastructure you control, the hosted server does not satisfy it. If your requirement is less configuration and fewer tokens per query, the hosted server does, and the README says as much.

## Maintenance, licence, and what an upgrade costs

The package is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are kept. That is a statement about the licence text, not legal advice; if you redistribute a modified build, read the LICENSE file in the repository and check how the Notion API terms apply to your integration separately.

The maintenance picture is the deciding factor. The README states that the project is no longer actively maintained or supported, that issues and pull requests are not actively monitored, and that Notion may sunset the repository. The last push was on 2026-09-20, and the latest release listed is v2.1.0 from 2026-01-31, while package.json reports version 2.5.2, so published releases and repository state are not moving in step. The practical upgrade cost is the tool surface: v2.0.0 renamed three database tools and changed database_id to data_source_id, and the Markdown tools depend on Notion API version 2026-03-11 while the rest use 2025-09-03. Any prompt or workflow that hardcodes tool names or assumes a single Notion-Version header has to be rechecked after every update, and no rollback procedure is documented.

## Conclusion

Use this repository if you need a local MCP server, already run Docker or Node, and accept that issues and pull requests are not actively monitored and that Notion may sunset the repository. Do not adopt it for new production integrations, because Notion only provides active support for Remote Notion MCP, which also removes the token and JSON configuration and enforces each user's existing Notion permissions. Before committing, verify the current tool list returned by the server against the v2.0.0 data source rename, and confirm whether the page Markdown tools still work, since they depend on the Notion API version 2026-03-11.

## FAQ

### What is Notion MCP Server?

It is a self-hosted Model Context Protocol server for the Notion API, published as @notionhq/notion-mcp-server and written in TypeScript. It exposes 22 Notion operations as MCP tools, including query-data-source and retrieve-page-markdown, so an MCP-capable AI client can search and edit a workspace.

### How do I set up Notion MCP Server?

Create an internal integration at notion.so/profile/integrations, connect the pages and databases it should reach through the Access tab or the page's Connect to integration menu, then point your MCP client at the package with OPENAPI_MCP_HEADERS holding your Authorization token. The README notes that an integration with no shared pages returns nothing.

### Is Notion MCP Server free?

The repository is MIT licensed, so the code itself costs nothing to use, modify or redistribute. Any cost attached to the Notion workspace or to the hosted Remote Notion MCP is not described in this repository's README.

### Is Notion MCP Server down?

This is a local server that runs on your own machine or in a Docker container, so there is no hosted endpoint of its own to go down. Failures you see are more likely to come from the Notion API, from an expired integration token, or from pages not being shared with the integration.

### How do I add Notion MCP Server to Claude Code?

The README's client configuration section covers adding an MCP server entry that launches the package, with the Notion credentials supplied through OPENAPI_MCP_HEADERS. The README does not give a Claude Code specific walkthrough, so use the same command and environment variable shown for other MCP clients.

## Sources

- [Issues](https://github.com/makenotion/notion-mcp-server/issues)
- [License: MIT](https://github.com/makenotion/notion-mcp-server/blob/main/LICENSE)
- [makenotion/notion-mcp-server on GitHub](https://github.com/makenotion/notion-mcp-server)
- [README](https://github.com/makenotion/notion-mcp-server/blob/main/README.md)
- [Releases](https://github.com/makenotion/notion-mcp-server/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/makenotion-notion-mcp-server