Can I use Gmail as a CLI?

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

Can I expose Gmail through MCP?

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

Where are Gmail credentials stored?

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

Can I deny write access for Gmail MCP tools?

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

productivity

Gmail CLI for AI Agents

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

Gmail CLI Setup

Gmail can be configured headlessly with `kosmokrator integrations:configure gmail`.

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 gmail --set access_token="$GMAIL_ACCESS_TOKEN" --enable --read allow --write ask --json
kosmokrator integrations:doctor gmail --json
kosmokrator integrations:status --json

Credentials

Authentication type: OAuth browser flow oauth2_authorization_code. Configure credentials once, then reuse the same stored profile from scripts, coding CLIs, Lua, and MCP.

Key	Env var	Type	Required	Label
`access_token`	`GMAIL_ACCESS_TOKEN`	OAuth token `oauth`	yes	Google Account

Command Patterns

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

Generic CLI call

kosmo integrations:call gmail.gmail_add_labels '{"message_id":"example_message_id","message_ids":"example_message_ids","label_ids":"example_label_ids"}' --json

Provider shortcut

kosmo integrations:gmail gmail_add_labels '{"message_id":"example_message_id","message_ids":"example_message_ids","label_ids":"example_label_ids"}' --json

Discovery

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

Discovery commands

kosmo integrations:docs gmail --json
kosmo integrations:docs gmail.gmail_add_labels --json
kosmo integrations:schema gmail.gmail_add_labels --json
kosmo integrations:search "Gmail" --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.

`gmail.gmail_add_labels`

Add labels to one or more Gmail messages. Provide messageIds (comma-separated) for batch operations.

Write write

Parameters: message_id, message_ids, label_ids

Generic call

kosmo integrations:call gmail.gmail_add_labels '{"message_id":"example_message_id","message_ids":"example_message_ids","label_ids":"example_label_ids"}' --json

Shortcut

kosmo integrations:gmail gmail_add_labels '{"message_id":"example_message_id","message_ids":"example_message_ids","label_ids":"example_label_ids"}' --json

`gmail.gmail_archive`

Archive one or more Gmail messages (remove from inbox). Provide messageIds (comma-separated) for batch operations.

Read read

Parameters: message_id, message_ids

Generic call

kosmo integrations:call gmail.gmail_archive '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

Shortcut

kosmo integrations:gmail gmail_archive '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

`gmail.gmail_create_draft`

Create a draft email in Gmail (not sent).

Write write

Parameters: to, subject, body, cc, bcc

Generic call

kosmo integrations:call gmail.gmail_create_draft '{"to":"example_to","subject":"example_subject","body":"example_body","cc":"example_cc","bcc":"example_bcc"}' --json

Shortcut

kosmo integrations:gmail gmail_create_draft '{"to":"example_to","subject":"example_subject","body":"example_body","cc":"example_cc","bcc":"example_bcc"}' --json

`gmail.gmail_mark_read`

Mark one or more Gmail messages as read. Provide messageIds (comma-separated) for batch operations.

Write write

Parameters: message_id, message_ids

Generic call

kosmo integrations:call gmail.gmail_mark_read '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

Shortcut

kosmo integrations:gmail gmail_mark_read '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

`gmail.gmail_mark_unread`

Mark one or more Gmail messages as unread. Provide messageIds (comma-separated) for batch operations.

Write write

Parameters: message_id, message_ids

Generic call

kosmo integrations:call gmail.gmail_mark_unread '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

Shortcut

kosmo integrations:gmail gmail_mark_unread '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

`gmail.gmail_read`

Read the full content of a Gmail message by its ID. Returns headers (From, To, Subject, Date), the decoded text body, and a list of attachments. Use gmail_search first to find message IDs, then use this tool to read the full content.

Read read

Parameters: message_id, format

Generic call

kosmo integrations:call gmail.gmail_read '{"message_id":"example_message_id","format":"example_format"}' --json

Shortcut

kosmo integrations:gmail gmail_read '{"message_id":"example_message_id","format":"example_format"}' --json

`gmail.gmail_remove_labels`

Remove labels from one or more Gmail messages. Provide messageIds (comma-separated) for batch operations.

Write write

Parameters: message_id, message_ids, label_ids

Generic call

kosmo integrations:call gmail.gmail_remove_labels '{"message_id":"example_message_id","message_ids":"example_message_ids","label_ids":"example_label_ids"}' --json

Shortcut

kosmo integrations:gmail gmail_remove_labels '{"message_id":"example_message_id","message_ids":"example_message_ids","label_ids":"example_label_ids"}' --json

`gmail.gmail_reply`

Reply to an existing Gmail message (maintains the thread).

Read read

Parameters: message_id, thread_id, body, to, cc, bcc

Generic call

kosmo integrations:call gmail.gmail_reply '{"message_id":"example_message_id","thread_id":"example_thread_id","body":"example_body","to":"example_to","cc":"example_cc","bcc":"example_bcc"}' --json

Shortcut

kosmo integrations:gmail gmail_reply '{"message_id":"example_message_id","thread_id":"example_thread_id","body":"example_body","to":"example_to","cc":"example_cc","bcc":"example_bcc"}' --json

`gmail.gmail_count_by_sender`

Count all matching Gmail messages grouped by sender. Automatically paginates through ALL results (handles thousands of messages). Returns top senders sorted by count. Use for questions like "who sends me the most email?" or "count unread by sender".

Read read

Parameters: query, label_ids

Generic call

kosmo integrations:call gmail.gmail_count_by_sender '{"query":"example_query","label_ids":"example_label_ids"}' --json

Shortcut

kosmo integrations:gmail gmail_count_by_sender '{"query":"example_query","label_ids":"example_label_ids"}' --json

`gmail.gmail_list_labels`

List all labels in the Gmail mailbox (INBOX, SENT, custom labels, etc.).

Read read

Parameters: none

Generic call

kosmo integrations:call gmail.gmail_list_labels '{}' --json

Shortcut

kosmo integrations:gmail gmail_list_labels '{}' --json

`gmail.gmail_save_attachment`

Download an email attachment and save it to workspace files. Requires a messageId and attachmentId (both returned by gmail_read). The file is saved under the agent's folder and can be browsed in the Files page.

Read read

Parameters: message_id, attachment_id, filename, mime_type

Generic call

kosmo integrations:call gmail.gmail_save_attachment '{"message_id":"example_message_id","attachment_id":"example_attachment_id","filename":"example_filename","mime_type":"example_mime_type"}' --json

Shortcut

kosmo integrations:gmail gmail_save_attachment '{"message_id":"example_message_id","attachment_id":"example_attachment_id","filename":"example_filename","mime_type":"example_mime_type"}' --json

`gmail.gmail_search_emails`

Search Gmail messages using Gmail query syntax (e.g., "from:alice subject:meeting is:unread has:attachment after:2026-02-01"). Returns message summaries with headers. Max 100 per page.

Read read

Parameters: query, max_results, page_token, label_ids

Generic call

kosmo integrations:call gmail.gmail_search_emails '{"query":"example_query","max_results":1,"page_token":"example_page_token","label_ids":"example_label_ids"}' --json

Shortcut

kosmo integrations:gmail gmail_search_emails '{"query":"example_query","max_results":1,"page_token":"example_page_token","label_ids":"example_label_ids"}' --json

`gmail.gmail_send_draft`

Send a previously created Gmail draft by its ID.

Write write

Parameters: draft_id

Generic call

kosmo integrations:call gmail.gmail_send_draft '{"draft_id":"example_draft_id"}' --json

Shortcut

kosmo integrations:gmail gmail_send_draft '{"draft_id":"example_draft_id"}' --json

`gmail.gmail_send_email`

Send an email directly via Gmail.

Write write

Parameters: to, subject, body, cc, bcc

Generic call

kosmo integrations:call gmail.gmail_send_email '{"to":"example_to","subject":"example_subject","body":"example_body","cc":"example_cc","bcc":"example_bcc"}' --json

Shortcut

kosmo integrations:gmail gmail_send_email '{"to":"example_to","subject":"example_subject","body":"example_body","cc":"example_cc","bcc":"example_bcc"}' --json

`gmail.gmail_trash`

Move one or more Gmail messages to trash. Provide messageIds (comma-separated) for batch operations.

Read read

Parameters: message_id, message_ids

Generic call

kosmo integrations:call gmail.gmail_trash '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

Shortcut

kosmo integrations:gmail gmail_trash '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

`gmail.gmail_untrash`

Remove one or more Gmail messages from trash. Provide messageIds (comma-separated) for batch operations.

Read read

Parameters: message_id, message_ids

Generic call

kosmo integrations:call gmail.gmail_untrash '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

Shortcut

kosmo integrations:gmail gmail_untrash '{"message_id":"example_message_id","message_ids":"example_message_ids"}' --json

Function Schemas

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

gmail.gmail_add_labels 3 parameters

Schema command

kosmo integrations:schema gmail.gmail_add_labels --json

Parameter	Type	Required	Description
`message_id`	string	no	Single message ID to add labels to.
`message_ids`	string	no	Comma-separated message IDs for batch operations.
`label_ids`	string	yes	Comma-separated label IDs to add.

gmail.gmail_archive 2 parameters

Schema command

kosmo integrations:schema gmail.gmail_archive --json

Parameter	Type	Required	Description
`message_id`	string	no	Single message ID to archive.
`message_ids`	string	no	Comma-separated message IDs for batch operations.

gmail.gmail_create_draft 5 parameters

Schema command

kosmo integrations:schema gmail.gmail_create_draft --json

Parameter	Type	Required	Description
`to`	string	yes	Recipient email address.
`subject`	string	yes	Email subject.
`body`	string	no	Email body text.
`cc`	string	no	CC recipients (comma-separated emails).
`bcc`	string	no	BCC recipients (comma-separated emails).

gmail.gmail_mark_read 2 parameters

Schema command

kosmo integrations:schema gmail.gmail_mark_read --json

Parameter	Type	Required	Description
`message_id`	string	no	Single message ID to mark as read.
`message_ids`	string	no	Comma-separated message IDs for batch operations.

gmail.gmail_mark_unread 2 parameters

Schema command

kosmo integrations:schema gmail.gmail_mark_unread --json

Parameter	Type	Required	Description
`message_id`	string	no	Single message ID to mark as unread.
`message_ids`	string	no	Comma-separated message IDs for batch operations.

gmail.gmail_read 2 parameters

Schema command

kosmo integrations:schema gmail.gmail_read --json

Parameter	Type	Required	Description
`message_id`	string	yes	Gmail message ID to read.
`format`	string	no	Response format: "full" (default, includes body), "metadata" (headers only), "minimal" (IDs only).

gmail.gmail_remove_labels 3 parameters

Schema command

kosmo integrations:schema gmail.gmail_remove_labels --json

Parameter	Type	Required	Description
`message_id`	string	no	Single message ID to remove labels from.
`message_ids`	string	no	Comma-separated message IDs for batch operations.
`label_ids`	string	yes	Comma-separated label IDs to remove.

gmail.gmail_reply 6 parameters

Schema command

kosmo integrations:schema gmail.gmail_reply --json

Parameter	Type	Required	Description
`message_id`	string	yes	Original message ID to reply to.
`thread_id`	string	yes	Thread ID to reply in.
`body`	string	yes	Reply body text.
`to`	string	no	Recipient email address (defaults to original sender).
`cc`	string	no	CC recipients (comma-separated emails).
`bcc`	string	no	BCC recipients (comma-separated emails).

gmail.gmail_count_by_sender 2 parameters

Schema command

kosmo integrations:schema gmail.gmail_count_by_sender --json

Parameter	Type	Required	Description
`query`	string	no	Gmail search query to filter messages (e.g., "is:unread", "after:2026-01-01").
`label_ids`	string	no	Comma-separated label IDs to filter by.

gmail.gmail_list_labels 0 parameters

Schema command

kosmo integrations:schema gmail.gmail_list_labels --json

Parameter	Type	Required	Description
No parameters.

gmail.gmail_save_attachment 4 parameters

Schema command

kosmo integrations:schema gmail.gmail_save_attachment --json

Parameter	Type	Required	Description
`message_id`	string	yes	Gmail message ID containing the attachment.
`attachment_id`	string	yes	Attachment ID from the gmail_read response.
`filename`	string	yes	Filename to save as (e.g. "invoice.pdf"). Use the filename from gmail_read.
`mime_type`	string	no	MIME type of the attachment (e.g. "application/pdf"). Use the mimeType from gmail_read.

gmail.gmail_search_emails 4 parameters

Schema command

kosmo integrations:schema gmail.gmail_search_emails --json

Parameter	Type	Required	Description
`query`	string	no	Gmail search query (e.g., "from:alice subject:meeting is:unread").
`max_results`	integer	no	Max results to return (default: 10, max: 100).
`page_token`	string	no	Pagination token from previous response.
`label_ids`	string	no	Comma-separated label IDs to filter by.

gmail.gmail_send_draft 1 parameters

Schema command

kosmo integrations:schema gmail.gmail_send_draft --json

Parameter	Type	Required	Description
`draft_id`	string	yes	Draft ID to send.

gmail.gmail_send_email 5 parameters

Schema command

kosmo integrations:schema gmail.gmail_send_email --json

Parameter	Type	Required	Description
`to`	string	yes	Recipient email address.
`subject`	string	yes	Email subject.
`body`	string	yes	Email body text.
`cc`	string	no	CC recipients (comma-separated emails).
`bcc`	string	no	BCC recipients (comma-separated emails).

gmail.gmail_trash 2 parameters

Schema command

kosmo integrations:schema gmail.gmail_trash --json

Parameter	Type	Required	Description
`message_id`	string	no	Single message ID to trash.
`message_ids`	string	no	Comma-separated message IDs for batch operations.

gmail.gmail_untrash 2 parameters

Schema command

kosmo integrations:schema gmail.gmail_untrash --json

Parameter	Type	Required	Description
`message_id`	string	no	Single message ID to restore from trash.
`message_ids`	string	no	Comma-separated message IDs for batch operations.

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.