A1 AI engineering company GitHub
Connect the Gmail MCP server to your AI agent Open source, MIT, on npm. Setup instructions for Claude, Cursor and Codex are in the repository; adoption questions — Telegram. GitHub repository Telegram

Gmail: Create, rename or delete a label — MCP tool

Gmail MCP tool: Manages the mailbox's user labels — creating, renaming, changing visibility or deleting them.

Technical name: manage_labels

What task it solves

I want to change the set of labels my mail is organized with.

Creates new filing categories, renames or hides existing ones, and removes labels that are no longer needed.

When to use it

When the organization scheme itself changes. To put mail *into* labels use modify_message/modify_thread, not this tool.

What to provide

  • action — required. create, update or delete.
  • name — required for create (nest with /, e.g. Clients/Acme — the parent must already exist); optional for update (rename).
  • label_id — required for update/delete. A user label id from list_labels.
  • label_list_visibility — optional. Sidebar visibility: show | show_if_unread | hide.
  • message_list_visibility — optional. Whether its messages show in the list: show | hide.

update changes only the provided fields.

What it returns

The created/updated label (id, name, visibility), or empty ({"deleted":true}) after a delete.

What changes in Gmail

create adds a label; update renames/re-hides it everywhere at once; delete removes the label from EVERY message it was applied to — the messages survive, but the label and its associations are gone irreversibly.

Example request

Create a label "Clients/Acme" and hide it from the sidebar unless it has unread mail.

Errors and limitations

System labels (INBOX, STARRED, ...) cannot be created, renamed or deleted. Creating a nested label whose parent does not exist fails — create the parent first. Deleting is not undoable; re-creating a label with the same name does not restore its message associations. Access also depends on token permissions, quotas, and upstream API limits.

Related MCP tools

Technical details