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

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

Related MCP server: Notion MCP Server

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:

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