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.jsondeclaresmcpName: io.github.ttaogaming/notion-fast.server.jsonmatches 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_blockis 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
