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.

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

Variable	Default	Description
NOTION_TOKEN	required	Notion internal integration token.
MCP_AUTH_TOKEN	unset	Optional bearer token for /mcp and /status.
EXPORT_DIR	/data/export	Markdown mirror root.
CACHE_DIR	/data/.cache	SQLite FTS index location.
PORT	3000	HTTP listen port.
BIND_HOST	0.0.0.0	HTTP listen address.
SYNC_INTERVAL_SECONDS	900	Incremental sync interval.
SYNC_OVERLAP_SECONDS	600	Overlap behind the derived watermark.
RECONCILE_EVERY_N_SYNCS	96	Full-reconcile cadence.
NOTION_RPS	2.5	Notion request budget.
NOTION_MAX_RETRIES	5	Retry limit for retryable Notion failures.
MIRROR_EXTERNAL_ASSETS	false	Also mirror non-Notion asset URLs.
SYNC_ON_STARTUP	true	Run a sync when the service starts.
LOG_LEVEL	info	Pino log level.

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