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
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.
Notion-Version header sent with every request; ntn --notion-version overrides it per line.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
__<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 tomarkdownand stay raw underblocks; blocks with children embed them underchildren. A row’s cell values are underproperties, as Notion’s own property objects; a standalone page’spropertiesholds only its title.database.json: the container:database_id,title,url, timestamps,parent,archived,is_inlineand thedata_sourcesthat name the folders beneath it. It carries noproperties.data_source.json: the typed column schema underproperties, 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’spage.jsonwithout the body, pluspath, where thatpage.jsonis below the data source folder.
Behavior
- Read only: the mount cannot change pages. Use the
ntnCLI, 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 -rorfindover a large database stays cheap. Row folders are not listed; open one by thepathon its line. Readingrows.jsonlcosts one query call per hundred rows.
Browser
The browserNotionVFS from @struktoai/mirage-browser talks to Notion’s MCP
server through an OAuth client provider, so no token sits in the page.
authProvideris anOAuthClientProviderfrom@modelcontextprotocol/client.serverUrlroutes MCP through another URL.
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>.
- Rendered
- Raw
Virtual Filesystem
VFS Layout
/<path>page.jsonholds the page’s metadata, its body as Markdown and its raw blocks.database.jsonlists a database’s data sources,data_source.jsonholds the property schema androws.jsonlone row per line, with itspathbelow the data source directory. Row directories are not listed; open one by thatpath.- Titles are sanitized:
lsthe parent or take a row’spathinstead of building paths. ntntakes ids as positional operands:ntn pages get <page-id>,ntn datasources query <data-source-id>,ntn datasources resolve <database-id>.
Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:
Run
man <cmd> or <cmd> --help for one command’s usage.