Gmail MCP

Gmail MCP gives your AI coding agent four Gmail tools and one admin tool, so you can ask it to list, read, search, and send email without leaving the editor. It is free, it runs as a VS Code extension, and it talks to your own Google account.

There is no server to host and no config file to edit. You install the extension, sign in to Google once, and the Gmail tools appear in every agent it finds on your machine: VS Code Copilot, Claude Code, Cursor, OpenAI Codex, Google Gemini, Windsurf, Continue.dev, and Cline.

What you can ask

These work as ordinary questions to your agent once the extension is running:

  • “Show me my last 10 emails”
  • “Find emails from my manager this week”
  • “Read the one about the invoice”
  • “Draft a reply saying Thursday works”
  • “Label everything from the hosting company as Billing”
  • “Send the team a note about the release”

The four Gmail MCP tools

Tool What it does
gmail_list List recent emails with metadata
gmail_read Read the full content of one email by ID
gmail_search Search using Gmail’s own query syntax
gmail_send Send an email

gmail_search takes the same operators you type into the Gmail search box, such as from:, newer_than:7d, has:attachment, and is:unread. If a search works in Gmail, the agent can run it.

The Gmail admin tool

Everything that changes your mailbox, apart from sending, lives in one admin tool with named actions.

Action What it does
create_draft, update_draft Write a draft or change one
delete_draft Delete a draft (needs confirmation)
add_label, remove_label Put a label on a message or take it off
create_label, delete_label Create or delete a label
trash, untrash Move a message to the trash or back (trash needs confirmation)
mark_read, mark_unread Change the read status

Trash and delete need explicit confirmation

Trashing a message and deleting a draft only run with confirm: true. The agent is told this up front, so it has to ask you before it does either. Reading, searching, and labelling do not need it.

Connecting your Gmail account

A setup wizard opens the first time you launch the extension. Most people pick OAuth.

  1. Create a project in the Google Cloud Console, or pick one you already have.
  2. Enable the Gmail API under APIs and Services.
  3. Create an OAuth client ID of type Desktop app.
  4. Paste the client ID and secret into the wizard.
  5. Sign in to Google in the browser window that opens, and authorize.

If your consent screen is set to External, add yourself as a test user first. Developers who already use the gcloud CLI can use Application Default Credentials instead. Workspace admins can use a service account key, which needs domain-wide delegation for Gmail.

Common questions

Does it cover other Google services?

Yes. The same install also gives you the Google Drive, Google Calendar, Docs, and Sheets tools.

Does it work with a personal Gmail account?

Yes. OAuth works with personal Gmail and with Google Workspace accounts.

Can the agent send email without asking me?

gmail_send is an ordinary tool call, so your agent’s own permission settings decide whether it asks first. If you would rather review every message, ask for a draft instead; create_draft leaves it in your Drafts folder.

Install it

Gmail MCP is free and MIT licensed. In the extension stores it is listed as Google Workspace MCP, the package that carries the Gmail tools.

Related