> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routemcp.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Notion

> Notion API — search, read, and write Notion pages, databases, blocks, and comments. 39 tools accessible through the MCP runtime endpoint.

<img src="https://icon.horse/icon/notion.so" alt="Notion" style={{ width: "48px", height: "48px", marginBottom: "16px" }} />

## Overview

| Property   | Value                    |
| ---------- | ------------------------ |
| Slug       | `notion`                 |
| Category   | Productivity             |
| Auth       | OAuth 2.0                |
| Base URL   | `https://api.notion.com` |
| Tool count | 39                       |
| Rate limit | 3 req/sec, 100 req/min   |

## Supported tools

All 39 slugs surfaced through MCP:

| Area          | Slugs                                                                                                                                                                                                  |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Users         | `NOTION_GET_ABOUT_ME`, `NOTION_LIST_USERS`, `NOTION_GET_USER`                                                                                                                                          |
| Search        | `NOTION_SEARCH`                                                                                                                                                                                        |
| Pages         | `NOTION_RETRIEVE_PAGE`, `NOTION_GET_PAGE_PROPERTY`, `NOTION_CREATE_PAGE`, `NOTION_UPDATE_PAGE`, `NOTION_ARCHIVE_PAGE`, `NOTION_MOVE_PAGE`, `NOTION_GET_PAGE_MARKDOWN`, `NOTION_UPDATE_PAGE_MARKDOWN`   |
| Databases     | `NOTION_RETRIEVE_DATABASE`, `NOTION_CREATE_DATABASE`, `NOTION_UPDATE_DATABASE`                                                                                                                         |
| Data sources  | `NOTION_RETRIEVE_DATA_SOURCE`, `NOTION_CREATE_DATA_SOURCE`, `NOTION_UPDATE_DATA_SOURCE`, `NOTION_QUERY_DATA_SOURCE`, `NOTION_LIST_DATA_SOURCE_TEMPLATES`                                               |
| Blocks        | `NOTION_RETRIEVE_BLOCK`, `NOTION_FETCH_BLOCK_CHILDREN`, `NOTION_APPEND_BLOCK_CHILDREN`, `NOTION_UPDATE_BLOCK`, `NOTION_DELETE_BLOCK`                                                                   |
| Comments      | `NOTION_CREATE_COMMENT`, `NOTION_LIST_COMMENTS`, `NOTION_RETRIEVE_COMMENT`, `NOTION_UPDATE_COMMENT`, `NOTION_DELETE_COMMENT`                                                                           |
| Views         | `NOTION_LIST_VIEWS`, `NOTION_CREATE_VIEW`, `NOTION_RETRIEVE_VIEW`, `NOTION_UPDATE_VIEW`, `NOTION_DELETE_VIEW`, `NOTION_CREATE_VIEW_QUERY`, `NOTION_GET_VIEW_QUERY_RESULTS`, `NOTION_DELETE_VIEW_QUERY` |
| Custom emojis | `NOTION_LIST_CUSTOM_EMOJIS`                                                                                                                                                                            |

## Connect setup

Notion uses OAuth 2.0 against a Notion **Public integration** you register in your workspace.

<Steps>
  <Step title="Create a Notion public integration">
    Go to [notion.so/profile/integrations](https://notion.so/profile/integrations) → **New integration**. Set the integration **Type** to **Public**.
  </Step>

  <Step title="Set Authentication method to OAuth">
    On the integration settings page, find the **Authentication method** section and pick **OAuth**. OAuth is user-scoped, supports multiple workspaces, and is the only method that works with RouteMCP's connect flow.
  </Step>

  <Step title="Add the redirect URL">
    Under **OAuth Domain & URIs**, add:

    ```
    https://api.routemcp.io/api/v1/connect/oauth/callback
    ```

    Copy the **OAuth Client ID** and **OAuth Client Secret** shown on the same page.
  </Step>

  <Step title="Grant capabilities">
    On the **Capabilities** tab, enable read / update / insert content and any user-information access your app needs. Notion treats these per-integration rather than as request-time scopes.
  </Step>

  <Step title="Connect via the widget">
    The end user opens the Connect widget, picks Notion, and is sent through Notion's consent screen to pick which workspaces and pages your integration may access.
  </Step>
</Steps>

## Usage

### Through the chat endpoint (recommended)

```bash theme={null}
curl -N -X POST "https://api.routemcp.io/api/v1/mcp/<workspace_id>/chat" \
  -H "x-api-key: sk_live_your_key" \
  -H "x-session-id: user-42" \
  -H "content-type: application/json" \
  -d '{"message": "Find my Notion page titled `Q3 planning` and append a bullet list of next-week action items."}'
```

The agent loop picks `NOTION_SEARCH` + `NOTION_APPEND_BLOCK_CHILDREN`, executes them, and streams the result back as SSE.

### Direct MCP JSON-RPC (Claude Desktop / Cursor / custom MCP clients)

```json theme={null}
{
  "mcpServers": {
    "routemcp": {
      "url": "https://api.routemcp.io/api/v1/mcp/<workspace_id>",
      "headers": {
        "x-api-key": "<YOUR_API_KEY>",
        "x-session-id": "<SESSION_ID>"
      }
    }
  }
}
```

Once connected, MCP clients can invoke any of the 39 tools by slug via the standard `tools/call` JSON-RPC method.