Can I use Notion as a CLI?

Yes. KosmoKrator exposes a Notion CLI through kosmo integrations:call and the provider shortcut command. Commands can return JSON for scripts, CI, and coding agents.

Can I expose Notion through MCP?

Yes. The KosmoKrator MCP gateway can expose selected Notion tools to clients such as Claude Code, Cursor, Codex, and other MCP-compatible tools.

Where are Notion credentials stored?

Notion credentials are configured in KosmoKrator's local integration settings and reused by CLI, Lua, and MCP gateway surfaces.

Can I deny write access for Notion MCP tools?

Yes. Start the gateway with --write=deny for read-only clients, or use ask/allow only for trusted workspaces.

productivity

Notion CLI for AI Agents

Use the Notion CLI from KosmoKrator to call Notion tools headlessly, return JSON, inspect schemas, and automate workflows from coding agents, scripts, and CI.

Notion CLI Setup

Notion can be configured headlessly with `kosmokrator integrations:configure notion`.

Install, configure, and verify

# Install KosmoKrator first if it is not available on PATH.
curl -fsSL https://raw.githubusercontent.com/OpenCompanyApp/kosmokrator/main/install.sh | bash

# Configure and verify this integration.
kosmokrator integrations:configure notion --set api_key="$NOTION_API_KEY" --enable --read allow --write ask --json
kosmokrator integrations:doctor notion --json
kosmokrator integrations:status --json

Credentials

Authentication type: API key api_key. Configure credentials once, then reuse the same stored profile from scripts, coding CLIs, Lua, and MCP.

Key	Env var	Type	Required	Label
`api_key`	`NOTION_API_KEY`	Secret `secret`	yes	API Key

Command Patterns

The generic command is stable across every integration. The provider shortcut is shorter for humans.

Generic CLI call

kosmo integrations:call notion.notion_search '{"query":"example_query","filter_type":"example_filter_type","sort_direction":"example_sort_direction","page_size":1,"start_cursor":"example_start_cursor"}' --json

Provider shortcut

kosmo integrations:notion notion_search '{"query":"example_query","filter_type":"example_filter_type","sort_direction":"example_sort_direction","page_size":1,"start_cursor":"example_start_cursor"}' --json

Discovery

These commands return structured output for coding agents that need to inspect capabilities before choosing a function.

Discovery commands

kosmo integrations:docs notion --json
kosmo integrations:docs notion.notion_search --json
kosmo integrations:schema notion.notion_search --json
kosmo integrations:search "Notion" --json
kosmo integrations:list --json

Automation Contexts

The same configured command surface works in these environments. The command does not change unless the host wrapper, credentials, or permissions change.

CI Run integration calls from CI jobs with JSON output, explicit credentials, and predictable exit status. Cron Jobs Schedule repeatable integration workflows from cron while keeping credentials in KosmoKrator config. Shell Scripts Call integration functions from shell scripts with stable JSON input and output. Headless Automation Use KosmoKrator as a non-interactive integration runtime for local automations and wrappers. Coding Agents Let coding agents discover schemas and execute integration functions through CLI commands or MCP.

CLI Functions

Every function below can be called headlessly. Commands are highlighted, copyable, and scroll horizontally when payloads are long.

`notion.notion_search`

Search pages and databases in your Notion workspace. Returns matching results with their IDs, types, and titles. Optionally filter by type (page or database) and control sort direction.

Read read

Parameters: query, filter_type, sort_direction, page_size, start_cursor

Generic call

kosmo integrations:call notion.notion_search '{"query":"example_query","filter_type":"example_filter_type","sort_direction":"example_sort_direction","page_size":1,"start_cursor":"example_start_cursor"}' --json

Shortcut

kosmo integrations:notion notion_search '{"query":"example_query","filter_type":"example_filter_type","sort_direction":"example_sort_direction","page_size":1,"start_cursor":"example_start_cursor"}' --json

`notion.notion_create_page`

Create a new page in Notion. The page can be created as a child of a database (to create a row) or as a child of another page (to create a sub-page). Provide properties as a JSON object matching the database schema when using a database parent. Provide children (block content) as a JSON array of block objects.

Write write

Parameters: parent_type, parent_id, properties, children

Generic call

kosmo integrations:call notion.notion_create_page '{"parent_type":"example_parent_type","parent_id":"example_parent_id","properties":"example_properties","children":"example_children"}' --json

Shortcut

kosmo integrations:notion notion_create_page '{"parent_type":"example_parent_type","parent_id":"example_parent_id","properties":"example_properties","children":"example_children"}' --json

`notion.notion_get_page`

Retrieve a Notion page by its ID. Returns the page object with properties, including title, icon, cover, parent info, and timestamps.

Read read

Parameters: page_id

Generic call

kosmo integrations:call notion.notion_get_page '{"page_id":"example_page_id"}' --json

Shortcut

kosmo integrations:notion notion_get_page '{"page_id":"example_page_id"}' --json

`notion.notion_update_page`

Update properties on a Notion page. Provide properties as a JSON object matching the database/page schema. Can also archive/unarchive the page.

Write write

Parameters: page_id, properties, archived

Generic call

kosmo integrations:call notion.notion_update_page '{"page_id":"example_page_id","properties":"example_properties","archived":true}' --json

Shortcut

kosmo integrations:notion notion_update_page '{"page_id":"example_page_id","properties":"example_properties","archived":true}' --json

`notion.notion_archive_page`

Archive a Notion page by setting its archived flag to true. The page can be restored by using notion_update_page with archived=false.

Write write

Parameters: page_id

Generic call

kosmo integrations:call notion.notion_archive_page '{"page_id":"example_page_id"}' --json

Shortcut

kosmo integrations:notion notion_archive_page '{"page_id":"example_page_id"}' --json

`notion.notion_create_database`

Create a new database as a child of a page. Provide the parent page ID, a title, and a properties schema. Properties define the columns of the database. Example properties: {"Name": {"title": {}}, "Status": {"select": {"options": [{"name": "Todo"}, {"name": "Done"}]}}}.

Write write

Parameters: parent_id, title, properties

Generic call

kosmo integrations:call notion.notion_create_database '{"parent_id":"example_parent_id","title":"example_title","properties":"example_properties"}' --json

Shortcut

kosmo integrations:notion notion_create_database '{"parent_id":"example_parent_id","title":"example_title","properties":"example_properties"}' --json

`notion.notion_get_database`

Retrieve a Notion database by its ID. Returns the full database schema including all property definitions (columns), title, and parent info.

Read read

Parameters: database_id

Generic call

kosmo integrations:call notion.notion_get_database '{"database_id":"example_database_id"}' --json

Shortcut

kosmo integrations:notion notion_get_database '{"database_id":"example_database_id"}' --json

`notion.notion_update_database`

Update a Notion database's title and/or property schema. Provide a new title and/or modified properties as a JSON object.

Write write

Parameters: database_id, title, properties

Generic call

kosmo integrations:call notion.notion_update_database '{"database_id":"example_database_id","title":"example_title","properties":"example_properties"}' --json

Shortcut

kosmo integrations:notion notion_update_database '{"database_id":"example_database_id","title":"example_title","properties":"example_properties"}' --json

`notion.notion_query_database`

Query a Notion database to retrieve rows (pages). Supports filtering and sorting. Filter and sorts can be provided as JSON strings or arrays. Example filter: {"property": "Status", "select": {"equals": "Done"}} Example sorts: [{"property": "Name", "direction": "ascending"}]

Read read

Parameters: database_id, filter, sorts, page_size, start_cursor

Generic call

kosmo integrations:call notion.notion_query_database '{"database_id":"example_database_id","filter":"example_filter","sorts":"example_sorts","page_size":1,"start_cursor":"example_start_cursor"}' --json

Shortcut

kosmo integrations:notion notion_query_database '{"database_id":"example_database_id","filter":"example_filter","sorts":"example_sorts","page_size":1,"start_cursor":"example_start_cursor"}' --json

`notion.notion_list_databases`

List all databases accessible to the integration. Uses the search endpoint filtered to database objects. Optionally provide a query to filter by name.

Read read

Parameters: query, page_size, start_cursor

Generic call

kosmo integrations:call notion.notion_list_databases '{"query":"example_query","page_size":1,"start_cursor":"example_start_cursor"}' --json

Shortcut

kosmo integrations:notion notion_list_databases '{"query":"example_query","page_size":1,"start_cursor":"example_start_cursor"}' --json

`notion.notion_get_block_children`

Get the child blocks of a Notion block or page. Returns a list of block objects. Use this to read the content of a page or to navigate nested block structures. Supports pagination.

Read read

Parameters: block_id, page_size, start_cursor

Generic call

kosmo integrations:call notion.notion_get_block_children '{"block_id":"example_block_id","page_size":1,"start_cursor":"example_start_cursor"}' --json

Shortcut

kosmo integrations:notion notion_get_block_children '{"block_id":"example_block_id","page_size":1,"start_cursor":"example_start_cursor"}' --json

`notion.notion_append_block_children`

Append blocks to a Notion page or block. Provide children as a JSON array of block objects. Example: [{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Hello world"}}]}}]

Write write

Parameters: block_id, children

Generic call

kosmo integrations:call notion.notion_append_block_children '{"block_id":"example_block_id","children":"example_children"}' --json

Shortcut

kosmo integrations:notion notion_append_block_children '{"block_id":"example_block_id","children":"example_children"}' --json

`notion.notion_get_block`

Retrieve a single Notion block by its ID. Returns the full block object including type-specific content, has_children flag, and parent info.

Read read

Parameters: block_id

Generic call

kosmo integrations:call notion.notion_get_block '{"block_id":"example_block_id"}' --json

Shortcut

kosmo integrations:notion notion_get_block '{"block_id":"example_block_id"}' --json

`notion.notion_update_block`

Update the content of a Notion block. Provide the block ID and the type-specific content to update. For example, to update a paragraph block, provide: {"type": "paragraph", "paragraph": {"rich_text": [{"text": {"content": "New text"}}]}} Only the fields you include will be updated.

Write write

Parameters: block_id, type, content, archived

Generic call

kosmo integrations:call notion.notion_update_block '{"block_id":"example_block_id","type":"example_type","content":"example_content","archived":true}' --json

Shortcut

kosmo integrations:notion notion_update_block '{"block_id":"example_block_id","type":"example_type","content":"example_content","archived":true}' --json

`notion.notion_delete_block`

Delete a Notion block by its ID. This permanently removes the block (moves it to trash if it is a top-level page block).

Write write

Parameters: block_id

Generic call

kosmo integrations:call notion.notion_delete_block '{"block_id":"example_block_id"}' --json

Shortcut

kosmo integrations:notion notion_delete_block '{"block_id":"example_block_id"}' --json

`notion.notion_get_current_user`

Get information about the current integration bot user. Returns the bot's name, avatar, and workspace info.

Read read

Parameters: none

Generic call

kosmo integrations:call notion.notion_get_current_user '{}' --json

Shortcut

kosmo integrations:notion notion_get_current_user '{}' --json

`notion.notion_list_users`

List all users in the Notion workspace. Returns user IDs, names, types, and avatar URLs. Supports pagination.

Read read

Parameters: page_size, start_cursor

Generic call

kosmo integrations:call notion.notion_list_users '{"page_size":1,"start_cursor":"example_start_cursor"}' --json

Shortcut

kosmo integrations:notion notion_list_users '{"page_size":1,"start_cursor":"example_start_cursor"}' --json

`notion.notion_get_user`

Retrieve a Notion user by their ID. Returns the user's name, type, avatar URL, and email (if available).

Read read

Parameters: user_id

Generic call

kosmo integrations:call notion.notion_get_user '{"user_id":"example_user_id"}' --json

Shortcut

kosmo integrations:notion notion_get_user '{"user_id":"example_user_id"}' --json

`notion.notion_create_comment`

Create a comment on a Notion page. You can either start a new discussion (provide parent_id) or reply to an existing discussion (provide discussion_id). Provide body_text for simple text, or body_children for rich content blocks.

Write write

Parameters: parent_id, discussion_id, body_text, body_children

Generic call

kosmo integrations:call notion.notion_create_comment '{"parent_id":"example_parent_id","discussion_id":"example_discussion_id","body_text":"example_body_text","body_children":"example_body_children"}' --json

Shortcut

kosmo integrations:notion notion_create_comment '{"parent_id":"example_parent_id","discussion_id":"example_discussion_id","body_text":"example_body_text","body_children":"example_body_children"}' --json

`notion.notion_get_comments`

Retrieve comments on a Notion page or block. Returns all comment objects with their content, authors, and timestamps. Supports pagination.

Read read

Parameters: block_id, page_size, start_cursor

Generic call

kosmo integrations:call notion.notion_get_comments '{"block_id":"example_block_id","page_size":1,"start_cursor":"example_start_cursor"}' --json

Shortcut

kosmo integrations:notion notion_get_comments '{"block_id":"example_block_id","page_size":1,"start_cursor":"example_start_cursor"}' --json

Function Schemas

Use these parameter tables when building CLI payloads without calling integrations:schema first.

notion.notion_search 5 parameters

Schema command

kosmo integrations:schema notion.notion_search --json

Parameter	Type	Required	Description
`query`	string	no	Search query text.
`filter_type`	string	no	Filter results by type: "page" or "database".
`sort_direction`	string	no	Sort direction: "ascending" or "descending". Defaults to descending (last edited first).
`page_size`	integer	no	Number of results per page (max 100, default 10).
`start_cursor`	string	no	Pagination cursor from a previous response.

notion.notion_create_page 4 parameters

Schema command

kosmo integrations:schema notion.notion_create_page --json

Parameter	Type	Required	Description
`parent_type`	string	yes	Parent type: "database" or "page".
`parent_id`	string	yes	ID of the parent database or page.
`properties`	string	no	Page properties as a JSON object. For database parents, keys should match database property names.
`children`	string	no	Page content as a JSON array of block objects.

notion.notion_get_page 1 parameters

Schema command

kosmo integrations:schema notion.notion_get_page --json

Parameter	Type	Required	Description
`page_id`	string	yes	The ID of the page to retrieve.

notion.notion_update_page 3 parameters

Schema command

kosmo integrations:schema notion.notion_update_page --json

Parameter	Type	Required	Description
`page_id`	string	yes	The ID of the page to update.
`properties`	string	no	Properties to update as a JSON object.
`archived`	boolean	no	Whether to archive the page.

notion.notion_archive_page 1 parameters

Schema command

kosmo integrations:schema notion.notion_archive_page --json

Parameter	Type	Required	Description
`page_id`	string	yes	The ID of the page to archive.

notion.notion_create_database 3 parameters

Schema command

kosmo integrations:schema notion.notion_create_database --json

Parameter	Type	Required	Description
`parent_id`	string	yes	ID of the parent page where the database will be created.
`title`	string	yes	Title of the database.
`properties`	string	yes	Database property schema as a JSON object. Each key is a property name with its type config.

notion.notion_get_database 1 parameters

Schema command

kosmo integrations:schema notion.notion_get_database --json

Parameter	Type	Required	Description
`database_id`	string	yes	The ID of the database to retrieve.

notion.notion_update_database 3 parameters

Schema command

kosmo integrations:schema notion.notion_update_database --json

Parameter	Type	Required	Description
`database_id`	string	yes	The ID of the database to update.
`title`	string	no	New title for the database.
`properties`	string	no	Updated property schema as a JSON object. Only included properties will be updated.

notion.notion_query_database 5 parameters

Schema command

kosmo integrations:schema notion.notion_query_database --json

Parameter	Type	Required	Description
`database_id`	string	yes	The ID of the database to query.
`filter`	string	no	Filter condition as a JSON string or object.
`sorts`	string	no	Sort rules as a JSON array string or array.
`page_size`	integer	no	Number of results per page (max 100, default 100).
`start_cursor`	string	no	Pagination cursor from a previous response.

notion.notion_list_databases 3 parameters

Schema command

kosmo integrations:schema notion.notion_list_databases --json

Parameter	Type	Required	Description
`query`	string	no	Search query to filter database names.
`page_size`	integer	no	Number of results per page (max 100, default 10).
`start_cursor`	string	no	Pagination cursor from a previous response.

notion.notion_get_block_children 3 parameters

Schema command

kosmo integrations:schema notion.notion_get_block_children --json

Parameter	Type	Required	Description
`block_id`	string	yes	ID of the block or page to get children for.
`page_size`	integer	no	Number of results per page (max 100, default 100).
`start_cursor`	string	no	Pagination cursor from a previous response.

notion.notion_append_block_children 2 parameters

Schema command

kosmo integrations:schema notion.notion_append_block_children --json

Parameter	Type	Required	Description
`block_id`	string	yes	ID of the parent block or page to append children to.
`children`	string	yes	Array of block objects to append, as a JSON string or array.

notion.notion_get_block 1 parameters

Schema command

kosmo integrations:schema notion.notion_get_block --json

Parameter	Type	Required	Description
`block_id`	string	yes	The ID of the block to retrieve.

notion.notion_update_block 4 parameters

Schema command

kosmo integrations:schema notion.notion_update_block --json

Parameter	Type	Required	Description
`block_id`	string	yes	The ID of the block to update.
`type`	string	no	Block type to update (e.g., "paragraph", "heading_1", "to_do").
`content`	string	no	Type-specific block content as a JSON object. For example: {"rich_text": [{"text": {"content": "Updated text"}}]}
`archived`	boolean	no	Whether to archive the block.

notion.notion_delete_block 1 parameters

Schema command

kosmo integrations:schema notion.notion_delete_block --json

Parameter	Type	Required	Description
`block_id`	string	yes	The ID of the block to delete.

notion.notion_get_current_user 0 parameters

Schema command

kosmo integrations:schema notion.notion_get_current_user --json

Parameter	Type	Required	Description
No parameters.

notion.notion_list_users 2 parameters

Schema command

kosmo integrations:schema notion.notion_list_users --json

Parameter	Type	Required	Description
`page_size`	integer	no	Number of results per page (max 100, default 100).
`start_cursor`	string	no	Pagination cursor from a previous response.

notion.notion_get_user 1 parameters

Schema command

kosmo integrations:schema notion.notion_get_user --json

Parameter	Type	Required	Description
`user_id`	string	yes	The ID of the user to retrieve.

notion.notion_create_comment 4 parameters

Schema command

kosmo integrations:schema notion.notion_create_comment --json

Parameter	Type	Required	Description
`parent_id`	string	no	Page ID to create a comment on. Required if discussion_id is not provided.
`discussion_id`	string	no	Discussion ID to reply to. Required if parent_id is not provided.
`body_text`	string	no	Simple text content for the comment.
`body_children`	string	no	Rich text block content as a JSON array of block objects.

notion.notion_get_comments 3 parameters

Schema command

kosmo integrations:schema notion.notion_get_comments --json

Parameter	Type	Required	Description
`block_id`	string	yes	The ID of the block or page to get comments for.
`page_size`	integer	no	Number of results per page (max 100, default 100).
`start_cursor`	string	no	Pagination cursor from a previous response.

Permissions

Headless calls still follow the integration read/write permission policy. Configure read/write defaults with integrations:configure. Add --force only for trusted automation that should bypass that policy.