# mcp-notion-fast

Lightweight, current-version Notion server for the [Model Context Protocol](https://modelcontextprotocol.io/). 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:

```bash
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:

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

Example client configuration:

```json
{
  "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

```bash
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.

```bash
npx wrangler secret put NOTION_API_KEY
npm run deploy
```

After deployment, connect a Streamable HTTP client to:

```text
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](SECURITY.md) for reporting guidance and deployment cautions.

## License

MIT