Skip to main content
Glama
sat899

Gmail MCP Assistant

by sat899
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Gmail MCP Assistant

A Model Context Protocol (MCP) server that enables Anthropic's Claude to read unread emails and create draft responses using the Gmail API.

Prerequisites

  • Python 3.10+

  • uv (Python package manager)

  • Claude Desktop app installed

  • A Google Cloud Project with the Gmail API enabled

Related MCP server: Gmail MCP Local Server

Setup

1. Google Cloud Configuration

  1. Go to the Google Cloud Console and create a new project

  2. Enable the Gmail API

  3. Configure the OAuth Consent Screen and add your email as a Test User

  4. Create OAuth 2.0 Credentials for a Desktop Application

  5. Download the JSON file, rename it to client_secret.json, and place it in this project's root directory

2. Installation

# Install dependencies
uv sync

3. Authentication

On first run, Claude Desktop will start the server and open a browser window for OAuth authentication. After authorizing, a token.json file will be created for future use.

4. Claude Desktop Configuration

Add this server to your Claude Desktop MCP configuration file. Edit claude_desktop_config.json and add:

{
  "mcpServers": {
    "gmail-assistant": {
      "command": "C:\\Users\\Satyam\\.local\\bin\\uv.exe", 
      "args": [
        "--directory",
        "C:\\Users\\Satyam\\Downloads\\mlx_application",
        "run",
        "server.py"
      ]
    }
  }
}

Update the paths to match your system:

  • command: Path to your uv.exe executable (you can get this by running uv where)

  • --directory: Path to this project directory

After saving the configuration, restart Claude Desktop to load the server.

Usage

Once configured, you can use the tools in Claude Desktop. Simply start a chat and ask something like 'What emails do I need to respond to?'. Claude will use the following tools:

  • get_unread_emails: Retrieve unread emails from your inbox

  • create_draft_reply: Create a draft reply for a specific email thread

Available Tools

2 tools
create_draft_replyC

Creates a draft reply for a specific thread.

ParametersJSON Schema
NameRequiredDescriptionDefault
thread_idYes
reply_textYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full behavioral burden. It implies the result is a draft rather than a sent message (useful), but says nothing about required permissions, whether it appends to or overwrites an existing draft, which folder it lands in, or what happens on an invalid thread_id.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence with the verb and scope front-loaded and no filler. It is well sized for what it attempts, though brevity here comes partly from omission rather than precision.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a write/create tool with no annotations, no output schema, and 0% parameter coverage, the description should disclose far more. It gives no auth requirements, no draft-lifecycle behavior, and no return information, so an agent cannot call it confidently.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description needed to compensate and does not. It never explains thread_id (format/lookup source) or reply_text (plain text vs markdown, length limits), leaving both required parameters undocumented in both schema and description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('Creates a draft reply') and a scope ('for a specific thread'), so the agent knows exactly what the tool produces. It does not explicitly contrast with the sibling get_unread_emails, but the read/write distinction is clear from the verb.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use guidance, no prerequisites, and no mention of alternatives such as sending a reply directly versus drafting one. The agent is left to infer that this is the compose-not-send path.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_unread_emailsC

Fetches a list of unread emails from the user's inbox.

ParametersJSON Schema
NameRequiredDescriptionDefault
max_resultsNo

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full behavioral burden and mostly does not: it never states that this is a read-only operation, what happens with pagination or truncation, whether results are capped, or what the returned list contains. Only the 'unread' and 'inbox' scope is conveyed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One compact sentence with the resource and scope front-loaded; nothing is wasted, though it is arguably under-specified rather than optimally concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read tool with no output schema the description is minimally viable, but it omits the behavior of max_results and any notion of result ordering or limits, which an agent would want before calling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter max_results has 0% schema description coverage, so the description is the only possible place to explain it, yet it says nothing about the parameter. Its default of 5, valid range, and unit of measurement are all left undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (fetches) and resource (unread emails) scoped to the user's inbox, so the operation is unambiguous. It does not explicitly differentiate from the sibling create_draft_reply, though the sibling's purpose is obviously distinct.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use or when-not-to-use guidance is given, nor is any prerequisite (e.g., authentication, mailbox state) mentioned. The agent must infer that this is the right call whenever unread mail is needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedcreate_draft_reply
    • First observedget_unread_emails
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one retrieves unread emails, the other creates a draft reply. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tool names follow a consistent verb_noun pattern in snake_case (get_unread_emails, create_draft_reply). The naming is predictable and readable.

Tool Count3/5

With only two tools, the set is quite thin for a Gmail assistant, which typically involves many operations. It is borderline but not an extreme mismatch.

Completeness2/5

Major gaps exist: no tools for sending emails, reading individual message content, searching, marking as read, or deleting. An agent cannot complete common email workflows with these two tools alone.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • gmail-mcp-server

    ihiteshgupta
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables reading, sending, searching, and managing Gmail through Claude using the official Google Gmail API.
    87 npm
    3
    MIT

  • Gmail MCP Server

    glrta
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables Claude to read unread emails and create draft replies in Gmail with proper threading.
    -