magic-notion-mcp

Local-first Notion sync + search MCP server powered by magic-retrieval from npm.

What it does

• syncs pages and data sources visible to one or more Notion integrations into a local embedded index
• stores retrieval state in local SQLite + LanceDB via magic-retrieval
• persists local sync state so it can do incremental polling without webhooks
• lets you search indexed Notion documents through CLI or MCP
• lets you read the locally indexed representation of a page or data source by id
• supports direct live reads from the Notion API through MCP
• defaults to strict read-only MCP mode; write tools are only exposed in read-write
• runs periodic background sync and periodic full reconciliation to detect edits, additions, and removals automatically

Install

npm install magic-notion-mcp

Quick setup

1. Create config:

npx -y magic-notion-mcp init-config

2. Fill in ~/.config/magic-notion-mcp/.env:

• NOTION_API_KEY for a single token, or
• NOTION_API_KEYS / NOTION_CREDENTIALS_JSON for multiple workspaces
• optional OPENAI_API_KEY

3. Check config:

npx -y magic-notion-mcp doctor

4. Inspect resolved workspaces:

npx -y magic-notion-mcp workspaces

5. Run a sync:

npx -y magic-notion-mcp sync

6. Search the local index:

npx -y magic-notion-mcp search --query "project roadmap"

7. Inspect overall sync health:

npx -y magic-notion-mcp sync-status

Configuration

Main settings:

• DB_PATH — SQLite path used by magic-retrieval
• LANCEDB_PATH — local LanceDB directory
• NOTION_API_KEY — backwards-compatible single token
• NOTION_API_KEYS — comma/newline-separated list of tokens for syncing multiple workspaces
• NOTION_CREDENTIALS_JSON — JSON array of strings or { id, label, token } objects for multi-token setup
• NOTION_MCP_MODE — read-only (default) or read-write
• NOTION_MCP_BACKGROUND_SYNC — true by default; runs sync asynchronously when the MCP server starts
• NOTION_SYNC_STATE_PATH — local durable state file used for incremental sync and status
• NOTION_SYNC_POLL_INTERVAL_MS — polling interval for background incremental sync
• NOTION_FULL_RESYNC_INTERVAL_MS — reconciliation interval for full scans that detect removals and heal drift
• NOTION_SYNC_CONCURRENCY — bounded parallelism for page content hydration during sync
• OPENAI_API_KEY — optional; without it search still works lexically
• NOTION_SYNC_PAGE_LIMIT — optional cap for sync runs read-only means write tools are not registered at all. They do not appear in MCP tool discovery. read-write enables a controlled set of page creation and update tools.

The sync model is:

• background polling for incremental change detection
• persistent local sync state to remember what was already indexed
• periodic full reconciliation to catch deletions/lost access and repair drift
• no webhooks required read-only means write tools are not registered at all. They do not appear in MCP tool discovery. read-write enables a controlled set of page creation and update tools.

CLI commands

• npx -y magic-notion-mcp doctor
• npx -y magic-notion-mcp workspaces
• npx -y magic-notion-mcp sync-status
• npx -y magic-notion-mcp sync
• npx -y magic-notion-mcp sync --mode incremental
• npx -y magic-notion-mcp sync --mode full
• npx -y magic-notion-mcp search --query "..."
• npx -y magic-notion-mcp search --query "..." --object-type page
• npx -y magic-notion-mcp page --id <document-id>

Important behavior

• sync rebuilds the local search corpus from all pages and data sources visible to the configured integrations
• on MCP startup, sync begins in the background by default so tools become available immediately while the index refresh is still running
• normal background runs are incremental and use lastSuccessfulSyncAt cursors to pick up changed objects quickly
• periodic full reconciliation runs rescan the workspace, detect removals, and rebuild the full active corpus when needed
• sync-status / notion_sync_status report whether sync is running, percentage progress, whether the index is believed current, and whether it has been recently fully verified
• duplicate visibility across multiple tokens is deduplicated by Notion object id
• search and page operate on the local index
• after an initial sync, local search/page lookup continue to work even if you only want to query the stored index
• if OPENAI_API_KEY is missing, the package still works with lexical retrieval only
• multiple tokens broaden coverage, but they still only see content explicitly shared to each integration in Notion

MCP

{
  "command": "npx",
  "args": ["-y", "magic-notion-mcp-mcp"]
}

Read-only MCP tools

• notion_search
• notion_document
• notion_workspaces
• notion_sync
• notion_sync_status
• notion_live_page
• notion_data_source

Additional read-write MCP tools

Enabled only when NOTION_MCP_MODE=read-write:

• notion_create_page
• notion_update_page_properties
• notion_update_page_markdown