Skip to main content
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.

Install

Configure

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

Fields

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.
string
required
secret
Notion integration token.
string
default:"'https://api.notion.com/v1'"
Notion API root; override to point at a fake or proxy.
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

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.

Behavior

  • Read only: the mount cannot change pages. Use the 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.
  • authProvider is an OAuthClientProvider from @modelcontextprotocol/client.
  • serverUrl routes MCP through another URL.
object
required
secret
OAuthClientProvider from @modelcontextprotocol/client that authorizes the browser with Notion’s MCP server.
string
default:"'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.
  • head -n N: renders only the first N rows.

VFS.md

The VFS.md an agent reads with Notion mounted at /<path>.
Virtual FilesystemVFS Layout/<path>
  • 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 VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.