mcp-notion-fast

Lightweight, current-version Notion server for the Model Context Protocol. It exposes focused page, data-source, and block workflows over local stdio and Cloudflare Worker Streamable HTTP.

This project targets Notion API 2026-03-11. It uses the current data-source query API instead of the deprecated database query path.

Capabilities

MCP surface	Name	Operation
Tool	notion_status	Return non-secret configuration status
Tool	search_notion	Search shared pages or data sources
Tool	get_page	Retrieve a page and its properties
Tool	create_page	Create a page under a page or data source
Tool	update_page	Update properties, icon, cover, lock, or trash state
Tool	get_database	Retrieve a database container and discover data sources
Tool	query_data_source	Filter, sort, and paginate a data source
Tool	list_block_children	Paginate child blocks
Tool	append_block_children	Append blocks using the current position API
Tool	get_block	Retrieve one block
Tool	update_block	Update one block
Tool	delete_block	Move one block to trash
Resource	notion://server/status	Read non-secret server metadata
Prompt	notion_workflow	Produce a read-first workflow for a Notion objective

Write and destructive tools carry MCP annotations so compatible clients can apply confirmation policies.

Requirements

• Node.js 22 or newer
• A Notion integration token with only the capabilities the intended workflow needs
• The target pages/databases explicitly shared with that integration

Local installation

The package is not yet published to npm. Until operator approval is granted, install from source:

git clone https://github.com/TTaoGaming/mcp-notion-fast.git
cd mcp-notion-fast
npm ci
npm run build

Set the token in the process environment; never put it in MCP configuration committed to source control:

$env:NOTION_API_KEY = "your-notion-integration-token"
node dist/src/stdio.js

Example client configuration:

{
  "mcpServers": {
    "notion-fast": {
      "command": "node",
      "args": ["C:/absolute/path/mcp-notion-fast/dist/src/stdio.js"],
      "env": {
        "NOTION_API_KEY": "${NOTION_API_KEY}"
      }
    }
  }
}

Optional environment variables:

Variable	Default	Purpose
NOTION_API_VERSION	2026-03-11	Pin a supported Notion API version
NOTION_API_BASE_URL	https://api.notion.com	Override the API origin for tests or an approved proxy

Verify locally

npm run check
npm run inspector:list

npm run check compiles the Node and Worker entrypoints, runs the test suite, audits the dependency graph during npm ci, and performs a Wrangler dry-run bundle. inspector:list launches the server through the official MCP Inspector CLI and calls tools/list.

Cloudflare Worker

The Worker serves MCP at /mcp using Cloudflare's stateless createMcpHandler and the MCP TypeScript SDK v2.

npx wrangler secret put NOTION_API_KEY
npm run deploy

After deployment, connect a Streamable HTTP client to:

https://mcp-notion-fast.tommytai3.workers.dev/mcp

The public demo currently has no Notion credential bound, so discovery and notion_status work while data tools fail closed. The endpoint has no application-level OAuth layer; use Cloudflare Access or MCP OAuth before connecting a production workspace.

Registry readiness

• package.json declares mcpName: io.github.ttaogaming/notion-fast.
• server.json matches the GitHub namespace and npm package identity.
• npm publication is intentionally pending operator approval.
• MCP Registry submission is intentionally pending operator approval.

The MCP Registry hosts metadata rather than package artifacts, so npm publication must precede Registry submission.

Security model

• Tokens are read from runtime configuration and never returned by tools or resources.
• API failures return bounded status/code/message fields, not headers or credentials.
• Requests time out after 20 seconds by default.
• IDs are path-encoded and tool inputs are schema validated.
• delete_block is explicitly annotated as destructive.
• API access is limited by the Notion integration's capabilities and page sharing.

See SECURITY.md for reporting guidance and deployment cautions.

License

MIT