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.

communication

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.

16 functions 9 read 7 write OAuth browser flow auth

Submit Gmail feedback View package source

Gmail CLI Setup

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

# 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 use the same stored profile from scripts, coding CLIs, Lua code mode, and the MCP gateway.

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

Call Gmail Headlessly

Use the generic call form when another coding CLI or script needs a stable universal interface.

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

Use the provider shortcut form for shorter human-facing commands.

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

Agent Discovery Commands

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

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

All CLI Functions

Every function below can be called headlessly. The generic form is stable across all integrations; the provider shortcut is shorter but specific to Gmail.

`gmail.gmail_add_labels`

Write write

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

Parameters: message_id, message_ids, label_ids

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

`gmail.gmail_archive`

Read read

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

Parameters: message_id, message_ids

Generic CLI call

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

Provider shortcut

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

`gmail.gmail_create_draft`

Write write

Create a draft email in Gmail (not sent).

Parameters: to, subject, body, cc, bcc

Generic CLI call

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

Provider 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`

Write write

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

Parameters: message_id, message_ids

Generic CLI call

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

Provider shortcut

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

`gmail.gmail_mark_unread`

Write write

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

Parameters: message_id, message_ids

Generic CLI call

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

Provider shortcut

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

`gmail.gmail_read`

Read 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.

Parameters: message_id, format

Generic CLI call

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

Provider shortcut

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

`gmail.gmail_remove_labels`

Write write

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

Parameters: message_id, message_ids, label_ids

Generic CLI call

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

Provider 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`

Read read

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

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

Generic CLI 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

Provider 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`

Read read

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".

Parameters: query, label_ids

Generic CLI call

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

Provider shortcut

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

`gmail.gmail_list_labels`

Read read

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

Parameters: none

Generic CLI call

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

Provider shortcut

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

`gmail.gmail_save_attachment`

Read read

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.

Parameters: message_id, attachment_id, filename, mime_type

Generic CLI 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

Provider 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`

Read read

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.

Parameters: query, max_results, page_token, label_ids

Generic CLI 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

Provider 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`

Write write

Send a previously created Gmail draft by its ID.

Parameters: draft_id

Generic CLI call

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

Provider shortcut

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

`gmail.gmail_send_email`

Write write

Send an email directly via Gmail.

Parameters: to, subject, body, cc, bcc

Generic CLI call

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

Provider 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`

Read read

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

Parameters: message_id, message_ids

Generic CLI call

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

Provider shortcut

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

`gmail.gmail_untrash`

Read read

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

Parameters: message_id, message_ids

Generic CLI call

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

Provider 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`

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

Operation: Write write
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`

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

Operation: Read read
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`

Create a draft email in Gmail (not sent).

Operation: Write write
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`

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

Operation: Write write
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`

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

Operation: Write write
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`

Operation: Read read
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`

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

Operation: Write write
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`

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

Operation: Read read
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`

Operation: Read read
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`

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

Operation: Read read
Schema command: kosmo integrations:schema gmail.gmail_list_labels --json

Parameter	Type	Required	Description
No parameters.

`gmail.gmail_save_attachment`

Operation: Read read
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`

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.

Operation: Read read
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`

Send a previously created Gmail draft by its ID.

Operation: Write write
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`

Send an email directly via Gmail.

Operation: Write write
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`

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

Operation: Read read
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`

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

Operation: Read read
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.