Notion

NotionVFS exposes a Notion workspace as a filesystem. The Node SDK talks to the Notion REST API with an integration token; the Browser SDK talks to Notion’s MCP server with an OAuth client provider so secrets stay off the page.

Node

pnpm add @struktoai/mirage-node

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 })
await ws.shell('ls /notion/pages/')

Field	Description
`timeout` 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` required, secret	Notion integration token.
`baseUrl` default `'https://api.notion.com/v1'`	Notion API root; override to point at a fake or proxy.
`apiVersion` 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.

Browser

pnpm add @struktoai/mirage-browser @modelcontextprotocol/client

import { MountMode, NotionVFS, Workspace } from '@struktoai/mirage-browser'

const notion = new NotionVFS({
  authProvider, // OAuthClientProvider from @modelcontextprotocol/client
})

const ws = new Workspace({ '/notion': notion }, { mode: MountMode.READ })
await ws.shell('ls /notion/')

Field	Description
`authProvider` required, secret	`OAuthClientProvider` from `@modelcontextprotocol/client` that authorizes the browser with Notion’s MCP server.
`serverUrl` default `'https://mcp.notion.com/mcp'`	Notion MCP endpoint; override to route MCP through your own URL.

Fields marked secret are redacted in snapshots.

Mount mode

read. Edit pages through the ntn CLI.

Acting on Notion

Acting on Notion (creating, editing and trashing pages, querying data sources, and every route that has no typed verb) goes through the ntn CLI when installed.

VFS.md

The VFS.md an agent reads with Notion mounted at /<path>.

Rendered
Raw

Virtual Filesystem

Path	Description
`/<path>`	`notion`, read

VFS Layout

`/<path>`

/<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 rendered as Markdown and its raw blocks (nested blocks under children).
A database is a container plus one or more data sources. database.json holds the container’s identity and its data_sources stubs, data_source.json the typed property schema, and rows.jsonl the rows, one JSON line each: the row page’s page.json without the body, plus path, that page.json’s path below the data source directory. Row directories are not listed; open one by its path.
Titles are sanitized. Don’t construct paths: ls the parent directory, or take a row’s path from rows.jsonl.
ntn takes ids as positional operands, not flags: 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.

---
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 rendered as Markdown
  and its raw blocks (nested blocks under `children`).
- A database is a container plus one or more data sources.
  `database.json` holds the container's identity and its `data_sources`
  stubs, `data_source.json` the typed property schema, and `rows.jsonl`
  the rows, one JSON line each: the row page's `page.json` without the
  body, plus `path`, that `page.json`'s path below the data source
  directory. Row directories are not listed; open one by its path.
- Titles are sanitized. Don't construct paths: `ls` the parent
  directory, or take a row's `path` from `rows.jsonl`.
- `ntn` takes ids as positional operands, not flags:
  `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.

Since the 2025-09-03 API generation a database is a container of data sources, and both the column schema and the rows live on the data source: data_source.json and rows.jsonl. database.json is the container’s identity plus the data_sources stubs that name the directories beneath it, and carries no properties. The shape is identical to the Python connector:

{
  "database_id": "eeee1111-2222-3333-4444-555566667777",
  "title": "Tasks",
  "url": "https://www.notion.so/eeee1111222233334444555566667777",
  "created_time": "2026-01-01T00:00:00.000Z",
  "last_edited_time": "2026-01-02T00:00:00.000Z",
  "parent": { "type": "workspace", "workspace": true },
  "archived": false,
  "is_inline": false,
  "data_sources": [
    { "id": "d5000000-2222-3333-4444-555566667777", "name": "Tasks" }
  ]
}

data_source.json holds the typed column schema under properties, and rows.jsonl holds every row, one JSON object per line: the row’s page.json without the body, plus path, where that page.json is below the data source directory. The rows are one file rather than a directory each, because a query answers a hundred rows’ cells in one call while every row directory costs calls of its own to enter. A database row is itself a page: its page.json reports parent_type of data_source_id, and its cell values ride in the same file under properties. Row directories are not listed; open one by the path on its line. For full rows.jsonl and page.json field details and supported edits see the Python Notion docs.

Integration

What Notion answers through its own API, so fewer files are read. Integration explains each command.

Command	On Notion
`head -n N`	Renders only the first N rows

Getting Started

Access

AI Agents

VFS

CLIs

Runtimes

Node

Browser

Mount mode

Acting on Notion

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration

​Node

​Browser

​Mount mode

​Acting on Notion

​VFS.md

​Virtual Filesystem

​VFS Layout

/<path>

​Supported Unix Commands for VFS

​Limitations of Unix Commands for VFS

​Integration

Node

Browser

Mount mode

Acting on Notion

VFS.md

Virtual Filesystem

VFS Layout

`/<path>`

Supported Unix Commands for VFS

Limitations of Unix Commands for VFS

Integration