Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/server.py:187-194 (schema)

  Tool schema definition for 'gmail_list_labels' with no input parameters.
  Tool( name="gmail_list_labels", description="List all Gmail labels including both system labels (INBOX, SENT, etc.) and user-created labels. Returns label names and IDs.", inputSchema={ "type": "object", "properties": {}, "required": [] },
• src/mcp_gmail/server.py:1128-1131 (registration)

  Registration of all Gmail tools including 'gmail_list_labels' via the MCP server's list_tools handler.
  @server.list_tools() async def list_tools() -> list[Tool]: return GMAIL_TOOLS
• src/mcp_gmail/server.py:708-711 (handler)

  Tool handler in handle_call_tool that executes gmail_list_labels by calling GmailClient.get_labels() and formatting the result.
  elif name == "gmail_list_labels": labels = await client.get_labels() return [TextContent(type="text", text=_format_labels_detailed(labels))]
• src/mcp_gmail/gmail_client.py:380-388 (handler)

  Core handler implementation in GmailClient that calls the Gmail API to list all labels.
  async def get_labels(self) -> list[dict]: """Get all Gmail labels.""" try: results = self.service.users().labels().list(userId="me").execute() return results.get("labels", []) except HttpError as e: logger.error(f"Failed to get labels: {e}") raise
• src/mcp_gmail/server.py:1331-1365 (helper)

  Helper function to format the list of labels into a detailed text response, separating system and user labels.
  def _format_labels_detailed(labels: list[dict]) -> str: """Format labels list with full details for display. Args: labels: List of label dictionaries. Returns: str: Formatted string representation. """ lines = ["Gmail Labels:\n"] system_labels = [] user_labels = [] for label in labels: if label.get("type") == "system": system_labels.append(label) else: user_labels.append(label) if system_labels: lines.append("System Labels:") for label in sorted(system_labels, key=lambda x: x.get("name", "")): lines.append(f" - {label['name']} (ID: {label['id']})") if user_labels: lines.append("\nUser Labels:") for label in sorted(user_labels, key=lambda x: x.get("name", "")): color_info = "" if label.get("color"): color_info = f" [color: {label['color'].get('backgroundColor', 'default')}]" lines.append(f" - {label['name']} (ID: {label['id']}){color_info}") return "\n".join(lines)