Notion MCP

A self-hosted Streamable HTTP MCP server that mirrors a Notion workspace to local Markdown files. MCP tools read the local mirror only; they never make a Notion API request.

Docker deployment

Prerequisites: Docker with the Compose plugin, and a Notion internal integration token that has been connected to the pages and data sources to mirror.

1. Create a private Docker network shared with MCP clients:

   docker network create notion-mcp-client

2. Copy .env.example to .env and set NOTION_TOKEN. Set MCP_AUTH_TOKEN to protect /mcp and /status with a bearer token.

3. Start the server:

   docker compose up -d --build

The Compose service has no published host ports. It is reachable only by containers on notion-mcp-client, using http://notion-mcp:3000. Set MCP_NETWORK before docker compose up to use a differently named existing network.

The named notion-mcp-data volume persists the Markdown mirror and FTS index. Restarting the service retains them, so unchanged pages are not downloaded again.

The Linux x64 image measured 297 MiB in verification. The runtime stage contains only node:22-slim, production dependencies (including the native FTS binding), and compiled application output; compiler packages and development dependencies remain in the discarded build stage.

Related MCP server: Notion MCP Server

Client integration

Connect an MCP client container to the shared network. For example:

docker run --rm --network notion-mcp-client curlimages/curl \
  http://notion-mcp:3000/health

Configure a Streamable HTTP MCP client with URL http://notion-mcp:3000/mcp. When MCP_AUTH_TOKEN is set, send Authorization: Bearer <MCP_AUTH_TOKEN>. /health is intentionally public on the private Docker network; /mcp and /status always pass through the auth middleware.

Environment

Runbook

View service state and logs:

docker compose ps
docker compose logs -f notion-mcp

Check health from a sibling container:

docker run --rm --network notion-mcp-client curlimages/curl \
  http://notion-mcp:3000/health

Stop gracefully with docker compose stop. The process handles SIGTERM, stops scheduling new syncs, closes HTTP connections, and Compose allows up to 30 seconds before forceful termination. Do not remove notion-mcp-data unless you intend to discard the mirror and force a full sync on the next start.

To update, run docker compose up -d --build. To intentionally reset all local mirror and search data, run docker compose down -v.

Development

cp .env.example .env
pnpm install
pnpm build
pnpm start