Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/server_old.py:47-66 (registration)

  Registration of the gmail_search tool including its schema definition within the list_tools() function.

  Tool(
      name="gmail_search",
      description="Search emails using Gmail query syntax or natural language. "
      "Examples: 'from:john@example.com', 'subject:meeting', 'is:unread'",
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Gmail search query or natural language search",
              },
              "max_results": {
                  "type": "integer",
                  "description": "Maximum number of results (default: 20, max: 100)",
                  "default": 20,
              },
          },
          "required": ["query"],
      },
  ),

• src/mcp_gmail/server_old.py:295-304 (handler)

  Handler implementation in call_tool() that parses arguments, calls GmailClient.search_emails(), formats results with _format_email_list, and returns TextContent.

  if name == "gmail_search":
      query = arguments.get("query", "")
      max_results = arguments.get("max_results", 20)
      results = await client.search_emails(query, max_results)
      return [
          TextContent(
              type="text",
              text=_format_email_list(results),
          )
      ]

• src/mcp_gmail/gmail_client.py:318-321 (helper)

  GmailClient.search_emails method: converts tool parameters to SearchQuery object and delegates to list_emails() which performs the actual Gmail API search.

  async def search_emails(self, query: str, max_results: int = 20) -> list[EmailSummary]:
      """Simple search interface for natural language queries."""
      search = SearchQuery(query=query, max_results=max_results)
      return await self.list_emails(search)

• src/mcp_gmail/server_old.py:730-749 (helper)

  Helper function to format the list of EmailSummary objects returned from search into a readable text response.

  def _format_email_list(emails: list) -> str:
      """Format email list for display."""
      if not emails:
          return "No emails found."
  
      lines = [f"Found {len(emails)} email(s):\n"]
      for email in emails:
          status = "📬" if not email.is_read else "📭"
          star = "⭐" if email.is_starred else ""
          attachment = "📎" if email.has_attachments else ""
          categories = f" [{', '.join(email.categories)}]" if email.categories else ""
  
          lines.append(
              f"{status}{star}{attachment} **{email.subject}**{categories}\n"
              f"   From: {email.sender}\n"
              f"   Date: {email.date.strftime('%Y-%m-%d %H:%M')}\n"
              f"   ID: `{email.id}`\n"
              f"   {email.snippet[:100]}...\n"
          )
      return "\n".join(lines)