notion-mcp-server

A Notion MCP server, iterated to our preferences.

Lineage

makenotion/notion-mcp-server → mieubrisse/notion-mcp-server → this fork

The original MCP server was maintained by Notion's team. When they shifted focus to their remote MCP (Enterprise-only for database access), mieubrisse forked it to keep the local server alive and added data source support. We forked mieubrisse's version and iterated from there — fixing compatibility issues, expanding the OpenAPI spec, and adding custom composite tools tailored to our workflows.

This server is developed by Michael Han and MILO (his AI assistant), built to power MILO's Notion integration.

---

What We Changed

VS Code MCP Compatibility

The upstream spec caused VS Code's MCP client to silently disable tools — no error surface, just broken calls. Root cause: VS Code's JSON Schema validator rejects custom format specifiers ("uuid", "json", "date"), and when schema compilation warns, VS Code disables the tool entirely.

Fixes applied to scripts/notion-openapi.json:

• Removed all "format": "uuid", "format": "json" specifiers
• Simplified parentRequest schema — replaced complex oneOf/$ref with direct properties
• Removed destructiveHint annotation from tool definitions

Error Handling

Upstream errors in the proxy and HTTP client crashed the MCP connection, killing the agent session with no recovery path.

• proxy.ts: Wrapped unhandled non-HTTP errors to return structured { status, error_type, message } responses instead of throwing
• http-client.ts: Added catch-all for network errors without .response — wraps as HttpClientError with status 0

OpenAPI Spec Expansions

Block types — expanded blockObjectRequest from 3 to 22 supported types:

Category	Types Added
Headings	heading_1, heading_2, heading_3
Lists	numbered_list_item
Structure	quote, divider, table_of_contents, toggle, column_list, column
Rich blocks	callout (with emoji icon), code (with 70-language enum), equation, bookmark
Media	image, video, file (all external URL format)
Tables	table, table_row

Rich text annotations — added optional annotations to richTextRequest: bold, italic, underline, strikethrough, code, color (19-value enum)

Icon schema — updated both POST and PATCH page endpoints to support emoji and external icon types (e.g. Notion's native SVG icons like https://www.notion.so/icons/briefcase_brown.svg)

PATCH block fix — upstream API-update-a-block always failed because the schema named its wrapper property "type", which serialized as {"type": <content>} — exactly what Notion rejects in update-block requests. Fixed by surfacing block-specific properties (to_do, paragraph, heading_1, etc.) at the root level.

Cherry-Picks from Upstream

Source	Change
mieubrisse	Added retrieve-a-database endpoint (GET /v1/databases/{id})
mieubrisse	Added create-a-database endpoint (POST /v1/databases)
mieubrisse	Added required type discriminator to pageIdParentRequest / dataSourceIdParentRequest
makenotion	Sanitized HTTP client error logging (removed sensitive response data from console)
makenotion	Added withStringFallback() to parser — handles double-serialized JSON from MCP clients

---

Custom Tools

The largest addition. Five composite tools built on top of the raw Notion API, designed for agentic task management workflows.

upsert-task

Create or update a task in the Tasks DB by title. Searches for an existing non-trashed task with an exact title match. If found, patches the page properties (and appends body_blocks if provided). If not found, creates a new page with all properties and optional children.

Returns { action: 'created' | 'updated', page_id, url }.

batch-delete-checkboxes

Fetches all to_do blocks from a page/block and deletes them in parallel. By default only deletes checked (completed) boxes — set checked_only: false to delete all. Returns { deleted, total_found, errors }.

batch-update-tasks

Update multiple Notion tasks in a single tool call. Accepts an array of { page_id, properties } and patches each in parallel. Returns { updated, errors }.

morning-scan

Runs two parallel queries against the Tasks DB: today's active tasks (Today? = true, Status != Done) and overdue tasks (Due < today, Status != Done, Today? = false). Returns { today: Page[], overdue: Page[], scanned_at }.

check-and-create-recurring

Checks for recurring task templates and creates new instances when due. Designed for workflows that need periodic task generation without manual intervention.

---

Installation

Claude Code (via mcp add)

NOTION_TOKEN=ntn_**** claude mcp add -s user notionapi -- npx tsx /path/to/notion-mcp-server/scripts/start-server.ts

The NOTION_TOKEN env var must be available in your shell when Claude Code starts. We store it in macOS Keychain and export from ~/.zshrc:

# Store once
security add-generic-password -a "$USER" -s "NOTION_TOKEN" -w "ntn_****"

# In ~/.zshrc
export NOTION_TOKEN=$(security find-generic-password -a "$USER" -s "NOTION_TOKEN" -w 2>/dev/null)

After adding a new env var, relaunch Claude Code from terminal (source ~/.zshrc && claude) — desktop launchers won't pick up new shell exports.

Claude Desktop / Cursor

{
  "mcpServers": {
    "notionApi": {
      "command": "npx",
      "args": ["tsx", "/path/to/notion-mcp-server/scripts/start-server.ts"],
      "env": {
        "NOTION_TOKEN": "ntn_****"
      }
    }
  }
}

---

Development

npm install
npm run build
npm run dev       # tsx watch mode
npm test

See UPSTREAM_TRACKING.md for a detailed record of all local modifications, cherry-picks, and the debugging journey that uncovered the VS Code schema compatibility issues.