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

# Notion

> Virtualize a Notion workspace from Node or the browser.

`NotionVFS` mounts the Notion pages and databases shared with a connection as
read-only JSON files: pages with their content as Markdown, and databases with
their schema and rows. Set up the token as in [Notion setup](https://docs.mirage.strukto.ai/home/setup/notion.md).

## Install

```bash theme={null}
npm install @struktoai/mirage-node
```

## Configure

```ts theme={null}
import { MountMode, NotionVFS, Workspace } from '@struktoai/mirage-node'

const notion = new NotionVFS({ apiKey: process.env.NOTION_API_KEY! })
const ws = new Workspace({ '/notion': notion }, { mode: MountMode.READ })

const result = await ws.shell('tree -L 3 /notion && grep -r deadline /notion/pages')
console.log(result.stdoutText)
await ws.close()
```

`baseUrl` points at a proxy. `apiVersion` sets the `Notion-Version` header,
`2025-09-03` when unset.

### Fields

**timeout** `number` (default: DEFAULT\_TIMEOUT)

Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.

**apiKey** `string` *required*

Notion integration token.

**baseUrl** `string` (default: '[https://api.notion.com/v1](https://api.notion.com/v1)')

Notion API root; override to point at a fake or proxy.

**apiVersion** `string` (default: '2025-09-03')

`Notion-Version` header sent with every request; `ntn --notion-version` overrides it per line.

Fields marked secret are redacted in snapshots.

## Authentication

The token is an internal connection's API token (`ntn_...`) with the read
content capability. The connection reaches only the pages and databases
shared with it; child pages inherit access, so sharing a top-level page
exposes its whole subtree. A personal access token with the **Notion API**
capability also works: it acts with its creator's permissions and needs no
sharing. The update and insert content capabilities are only for writes
through the `ntn` CLI.

## Layout

```text theme={null}
/notion/
  pages/
    Engineering_Wiki__<page-id>/
      page.json
      Onboarding__<child-id>/
        page.json
  databases/
    Roadmap__<database-id>/
      database.json
      Roadmap__<data-source-id>/
        data_source.json
        rows.jsonl
```

Titles are sanitized and end in `__<id>`, so `ls` the parent instead of
building a path. `pages/` mirrors Notion's page tree, with child pages as
nested folders. Since the `2025-09-03` API, a database is a container of one
or more data sources, so `databases/` is one level deeper. A single-source
database repeats its name, since Notion names the data source after its
database.

* **`page.json`:** a page, a database row included. Blocks render to
  `markdown` and stay raw under `blocks`; blocks with children embed them
  under `children`. A row's cell values are under `properties`, as Notion's
  own property objects; a standalone page's `properties` holds only its
  title.
* **`database.json`:** the container: `database_id`, `title`, `url`,
  timestamps, `parent`, `archived`, `is_inline` and the `data_sources` that
  name the folders beneath it. It carries no `properties`.
* **`data_source.json`:** the typed column schema under `properties`, with no
  rows. A data source id is not its database id; `ntn datasources resolve <database-id>` turns one into the other.
* **`rows.jsonl`:** every row, one JSON object per line in query order: the
  row's `page.json` without the body, plus `path`, where that `page.json` is
  below the data source folder.

```bash theme={null}
jq -r 'select(.properties.Priority.number > 1) | .title' "$DS/rows.jsonl"
grep -c '"checkbox":true' "$DS/rows.jsonl"
cat "$DS/$(jq -r 'select(.title == "Write spec") | .path' "$DS/rows.jsonl")"
```

## Behavior

* **Read only:** the mount cannot change pages. Use the [`ntn`](https://docs.mirage.strukto.ai/typescript/cli/ntn)
  CLI, which takes the same token, to create, edit and trash pages, query data
  sources and reach every other route. Ids
  are positional: use the `<page-id>`, `<database-id>` or `<data-source-id>`
  from a path segment.
* **Rows in one file:** a query answers a hundred rows' cells in one call,
  while each row folder costs calls of its own, so rows are one file and
  `grep -r` or `find` over a large database stays cheap. Row folders are not
  listed; open one by the `path` on its line. Reading `rows.jsonl` costs one
  query call per hundred rows.

## Browser

The browser `NotionVFS` from `@struktoai/mirage-browser` talks to Notion's MCP
server through an OAuth client provider, so no token sits in the page.

```bash theme={null}
npm install @struktoai/mirage-browser @modelcontextprotocol/client
```

```ts theme={null}
import { MountMode, NotionVFS, Workspace } from '@struktoai/mirage-browser'

const notion = new NotionVFS({ authProvider })
const ws = new Workspace({ '/notion': notion }, { mode: MountMode.READ })
```

* `authProvider` is an `OAuthClientProvider` from `@modelcontextprotocol/client`.
* `serverUrl` routes MCP through another URL.

> [accordion] Browser fields
>
> **authProvider** `object` *required*
>
> `OAuthClientProvider` from `@modelcontextprotocol/client` that authorizes the browser with Notion's MCP server.
>
> **serverUrl** `string` (default: '[https://mcp.notion.com/mcp](https://mcp.notion.com/mcp)')
>
> Notion MCP endpoint; override to route MCP through your own URL.
>
> Fields marked secret are redacted in snapshots.

## Integration

Notion answers this command through its own API, so less is read. See
[Integration](https://docs.mirage.strukto.ai/home/integration/overview.md).

* `head -n N`: renders only the first N rows.

## VFS.md

The [VFS.md](https://docs.mirage.strukto.ai/home/setup/vfs-md.md) an agent reads with Notion mounted at `/<path>`.

> [tab] Rendered
>
> **Virtual Filesystem**
>
> | Path | Description |
> | - | - |
> | `/<path>` | `notion`, read |
>
> **VFS Layout**
>
> **`/<path>`**
>
> ```text theme={null}
> /<path>
>   pages/                                     # the page tree
>     <page-title>__<page-id>/
>       page.json
>       <child-page-title>__<child-id>/
>         page.json
>   databases/                                 # shared databases
>     <database-title>__<database-id>/
>       database.json
>       <data-source-title>__<data-source-id>/
>         data_source.json
>         rows.jsonl
> ```
>
> * `page.json` holds the page's metadata, its body as Markdown and its raw
>   blocks.
> * `database.json` lists a database's data sources, `data_source.json`
>   holds the property schema and `rows.jsonl` one row per line, with its
>   `path` below the data source directory. Row directories are not
>   listed; open one by that `path`.
> * Titles are sanitized: `ls` the parent or take a row's `path` instead of
>   building paths.
> * `ntn` takes ids as positional operands: `ntn pages get <page-id>`,
>   `ntn datasources query <data-source-id>`,
>   `ntn datasources resolve <database-id>`.
>
> **Supported Unix Commands for VFS**
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | - | - |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `head` asks `notion` instead of reading a file. |
>
> **Limitations of Unix Commands for VFS**
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | - | - |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.

> [tab] Raw
>
> ````markdown theme={null}
> ---
> name: workspace-filesystem
> description: The virtual filesystem layout of this workspace.
> ---
>
> # Virtual Filesystem
>
> | Path | Description |
> | --- | --- |
> | `/<path>` | `notion`, read |
>
> ## VFS Layout
>
> ### `/<path>`
>
> ```text
> /<path>
>   pages/                                     # the page tree
>     <page-title>__<page-id>/
>       page.json
>       <child-page-title>__<child-id>/
>         page.json
>   databases/                                 # shared databases
>     <database-title>__<database-id>/
>       database.json
>       <data-source-title>__<data-source-id>/
>         data_source.json
>         rows.jsonl
> ```
>
> - `page.json` holds the page's metadata, its body as Markdown and its raw
>   blocks.
> - `database.json` lists a database's data sources, `data_source.json`
>   holds the property schema and `rows.jsonl` one row per line, with its
>   `path` below the data source directory. Row directories are not
>   listed; open one by that `path`.
> - Titles are sanitized: `ls` the parent or take a row's `path` instead of
>   building paths.
> - `ntn` takes ids as positional operands: `ntn pages get <page-id>`,
>   `ntn datasources query <data-source-id>`,
>   `ntn datasources resolve <database-id>`.
>
> ## Supported Unix Commands for VFS
>
> Unix commands work on each path as on a local filesystem, as far as the path supports them:
>
> | Path | Supported |
> | --- | --- |
> | `/<path>` | Commands that read files (`ls`, `cat`, `grep`, `find`, `jq` and the rest). `head` asks `notion` instead of reading a file. |
>
> ## Limitations of Unix Commands for VFS
>
> Where a path differs from a local filesystem:
>
> | Path | Limitations |
> | --- | --- |
> | `/<path>` | Read only: no command changes files. `grep -r`, `find` and `du` stop after 1000 files; a glob matching more, `tar -c`, `cp -r` and `rm -r` are refused. |
>
> Run `man <cmd>` or `<cmd> --help` for one command's usage.
> ````


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.