שרת MCP מאומת: Gmail
רשימת הכלים למטה היא לכידה חיה מהשרת הרץ; קריאת כלי מאומתת עדיין ממתינה להרשאות.
התשובה הקצרה
אומת לאחרונה 2026-08-03
שרת ה-MCP ל-Gmail נותן לעוזר AI סדרת פעולות ב-Gmail: לחפש בתיבה, לקרוא הודעה, לשלוח או לנסח מייל, להעביר הודעות בין תוויות ולנהל מסננים. Google לא מפרסמת שרת כזה, ולכן הקהילה התכנסה סביב @gongrzhe/server-gmail-autoauth-mcp, שרץ על ה-Mac שלכם על גבי stdio מול לקוח OAuth שאתם יוצרים בעצמכם. הרצנו אותו, דיברנו איתו בפרוטוקול וספרנו את כל 19 הכלים שהוא חושף; הטבלה למטה היא הלכידה הזו, מילה במילה. מה שלא יכולנו לעשות הוא להשלים קריאה מאומתת: לשם כך נדרש פרויקט ב-Google Cloud עם Gmail API מופעל ותהליך אישור בדפדפן שהושלם, ולכן העמוד הזה מראה לכם את הכלים ואת השגיאות המדויקות שמתקבלות בלי אסימון, ועוצר שם. שני דברים ששווה לדעת לפני שמתחילים. מאגר המקור נמצא בארכיון ב-GitHub והדחיפה האחרונה אליו הייתה באוגוסט 2025, כלומר אף אחד לא ממזג לתוכו תיקונים. ובכל זאת, החבילה צברה 36,179 הורדות בשבוע האחרון. [1][2][3][6][7]
אימות
השיטה
הרצנו את השרת עם npx על גבי stdio עם קובץ לקוח OAuth מדומה ובלי אסימון שמור, השלמנו את לחיצת היד של MCP וקראנו ל-tools/list: 19 הכלים למטה הם התשובה הזו, מילה במילה. אחר כך ביצענו קריאת כלי אמיתית אחת, list_email_labels, והיא נכשלה, כפי שהיה חייב לקרות. קריאות מאומתות כאן ממתינות לאסימון OAuth של Google לחשבון Gmail אמיתי, שאין לנו, ולכן שום דבר בעמוד הזה לא טוען שקריאה מוצלחת מ-Gmail התרחשה. שני פרטים על הריצה: כיוונו את GMAIL_OAUTH_PATH ואת GMAIL_CREDENTIALS_PATH לתיקיית טיוטה כדי שהבדיקה לא תיגע בתיקיית ~/.gmail-mcp אמיתית, ופלט ההפעלה למטה הוא מה ש-npx הדפיס, כי השרת עצמו לא מדפיס באנר כשהוא עולה כשורה.
הודעת הפתיחה של השרת
npm warn deprecated node-domexception@1.0.0: Use your platform's native DOMException instead npm warn deprecated uuid@9.0.1: uuid@10 and below is no longer supported. For ESM codebases, update to uuid@latest. For CommonJS codebases, use uuid@11 (but be aware this version will likely be deprecated in 2028).
קריאת כלי אמיתית אחת
tools/call list_email_labels {}Error: Failed to list labels: No access, refresh token, API key or refresh handler callback is set.
שורות אמיתיות מהתוצאה שנלכדה: מספיק כדי להוכיח שהקריאה נענתה.
כלים
השרת ענה ל-tools/list עם 19 כלים בתאריך 2026-08-03. השמות, התיאורים והפרמטרים למטה הם המילים שלו עצמו, מועתקים מהתשובה הזו וללא עריכה.
| כלי | מה הוא עושה |
|---|---|
| send_emailto*subject*body*htmlBodymimeTypeccbccthreadIdinReplyToattachments | Sends a new email |
| draft_emailto*subject*body*htmlBodymimeTypeccbccthreadIdinReplyToattachments | Draft a new email |
| read_emailmessageId* | Retrieves the content of a specific email |
| search_emailsquery*maxResults | Searches for emails using Gmail search syntax |
| modify_emailmessageId*labelIdsaddLabelIdsremoveLabelIds | Modifies email labels (move to different folders) |
| delete_emailmessageId* | Permanently deletes an email |
| list_email_labels | Retrieves all available Gmail labels |
| batch_modify_emailsmessageIds*addLabelIdsremoveLabelIdsbatchSize | Modifies labels for multiple emails in batches |
| batch_delete_emailsmessageIds*batchSize | Permanently deletes multiple emails in batches |
| create_labelname*messageListVisibilitylabelListVisibility | Creates a new Gmail label |
| update_labelid*namemessageListVisibilitylabelListVisibility | Updates an existing Gmail label |
| delete_labelid* | Deletes a Gmail label |
| get_or_create_labelname*messageListVisibilitylabelListVisibility | Gets an existing label by name or creates it if it doesn't exist |
| create_filtercriteria*action* | Creates a new Gmail filter with custom criteria and actions |
| list_filters | Retrieves all Gmail filters |
| get_filterfilterId* | Gets details of a specific Gmail filter |
| delete_filterfilterId* | Deletes a Gmail filter |
| create_filter_from_templatetemplate*parameters* | Creates a filter using a pre-defined template for common scenarios |
| download_attachmentmessageId*attachmentId*filenamesavePath | Downloads an email attachment to a specified location |
פרמטרים המסומנים ב-* הם חובה.
התקנה
העתיקו את הבלוק של האפליקציה שלכם. כל אחד מהם הוא ההגדרה המדויקת שאיתה אימתנו את השרת.
פתחו את הקובץ ~/Library/Application Support/Claude/claude_desktop_config.json (בתוך Claude Desktop: Settings, אחר כך Developer, אחר כך Edit Config) והוסיפו:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"-y",
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}אין כאן שום אישור גישה, וזה בכוונה: השרת קורא במקום זאת שני קבצים מתוך ~/.gmail-mcp, את קובץ לקוח ה-OAuth שאתם מניחים שם ואת האסימון שנכתב בשלב ההתחברות החד-פעמי. הכינו קודם את שניהם: בלי קובץ הלקוח השרת יוצא עוד לפני ש-Claude Desktop מספיק לדבר איתו, ובלי האסימון הוא עולה אבל כל קריאה חוזרת כשגיאה. אחר כך סגרו ופתחו מחדש את Claude Desktop. [10][5]
פקודה אחת בטרמינל:
claude mcp add gmail -- npx -y @gongrzhe/server-gmail-autoauth-mcp
כל מה שאחרי המקף הכפול הוא הפקודה המדויקת ש-Claude Code יריץ, וזו הפקודה שהרצנו בריצת האימות. בצעו את שלב ההתחברות החד-פעמי לפניה. [11]
הוסיפו ל-~/.cursor/mcp.json עבור כל הפרויקטים, או ל-.cursor/mcp.json בתוך פרויקט אחד:
{
"mcpServers": {
"gmail": {
"command": "npx",
"args": [
"-y",
"@gongrzhe/server-gmail-autoauth-mcp"
]
}
}
}Cursor קורא את הקובץ מחדש אחרי הפעלה מחדש. אין בקובץ הזה שום דבר סודי, ולכן .cursor/mcp.json ברמת הפרויקט בטוח להעלאה ל-git; האסימונים יושבים ב-~/.gmail-mcp במקום. [12]
בלי קובץ JSON ובלי טרמינל עבור החיבור עצמו. ב-Routines: Settings, אחר כך Assistant, אחר כך Connections, אחר כך Add MCP Server. העבירו את הטופס ל-Command (stdio) והזינו:
Name Gmail Command npx Arguments -y @gongrzhe/server-gmail-autoauth-mcp
השאירו את Environment Variables ריק, אלא אם אתם שומרים את האישורים במקום אחר מ-~/.gmail-mcp, ואז הגדירו GMAIL_OAUTH_PATH ו-GMAIL_CREDENTIALS_PATH, אחד בכל שורה; כך כיוונו את ריצת האימות לתיקיית טיוטה. לחצו קודם על Test Connection: שרת תקין עונה עם מספר הכלים שלו, תשעה עשר עבור השרת הזה. [13]
בלי טרמינל
לשרת הזה יש שלב טרמינל אחד שאי אפשר לעקוף, אז עדיף להיות כנים לגביו מראש: אתם יוצרים לקוח OAuth של Google, מריצים פקודה אחת כדי להתחבר איתו, ומכאן הכל בלחיצות. Routines היא אפליקציית Mac שמריצה שרתי MCP בשבילכם, ואחרי שהשרת הזה נוסף הכלים שלו זמינים ל-AI שלכם בצ׳אט ובשגרות מתוזמנות.
01
הורידו את האפליקציה מ-getroutines.ai/download, גררו אותה ל-Applications והתחברו.
02
ב-Google Cloud Console צרו פרויקט, או בחרו קיים, והפעילו עליו את Gmail API. אחר כך פתחו APIs and Services, אחר כך Credentials, אחר כך Create Credentials, אחר כך OAuth client ID, ובחרו Desktop app. הורידו את קובץ ה-JSON ושנו את שמו ל-gcp-oauth.keys.json.
03
בטרמינל: mkdir -p ~/.gmail-mcp, העבירו את gcp-oauth.keys.json לתוך התיקיה הזו, ואז הריצו npx @gongrzhe/server-gmail-autoauth-mcp auth. הדפדפן נפתח, אתם מאשרים את הגישה, והפקודה שומרת אסימון בשם ~/.gmail-mcp/credentials.json. זה שלב הטרמינל היחיד, ועושים אותו פעם אחת.
04
לחצו על החשבון שלכם בתחתית סרגל הצד ובחרו Settings. פתחו את הקטע Assistant, אחר כך את הלשונית Connections, גללו אל MCP Servers ולחצו על Add MCP Server.
05
העבירו את הטופס ל-Command (stdio): השרת הזה הוא פקודה שרצה על ה-Mac שלכם, לא כתובת אינטרנט. קראו לו Gmail. Command: npx. Arguments: -y @gongrzhe/server-gmail-autoauth-mcp. השאירו את Environment Variables ריק; השרת מוצא את שני הקבצים ב-~/.gmail-mcp בעצמו.
06
לחצו Test Connection: Routines מפעילה את השרת ומדווחת כמה כלים היא מצאה, תשעה עשר עבור השרת הזה. אחר כך לחצו Add Server. הכלים עובדים בצ׳אט מיד; כדי לתת לשגרה מתוזמנת להשתמש בהם, פתחו את השגרה, מצאו את הכרטיס Tools & connections וסמנו את השרת תחת Apps.
רעיונות לשגרות
אחרי שהשרת מחובר, שגרה מתוזמנת יכולה להשתמש בכלים שלו גם כשאתם לא מול המסך. העתיקו פרומפט, הדביקו אותו ב-Routines ובחרו שעה. הפרומפטים כתובים באנגלית בכוונה, מדביקים אותם בדיוק כפי שהם.
Every weekday at 8:00, search my Gmail for unread messages from the last day, group them into things that need a reply, things that are just information, and newsletters, and write me a short list with one suggested next step for each.
Every Friday at 16:00, search my Gmail for emails I sent this week that nobody replied to, list them with the recipient and the subject, and write the list to inbox-followups.md.
Every Sunday at 19:00, search my Gmail for newsletters received in the last seven days, summarise each one in two sentences, and put the summaries in a single note ordered by how useful they look to me.
פתרון תקלות
שגיאות אמיתיות שנלכדו בריצת האימות, מודפסות בדיוק כפי שהשרת החזיר אותן.
מה רואים
Error: OAuth keys file not found. Please place gcp-oauth.keys.json in current directory or /tmp/gmail-mcp-probe/home/.gmail-mcp
הפתרון
השרת בודק את קובץ לקוח ה-OAuth עוד לפני שהוא אומר מילה אחת ב-MCP, ויוצא אם הקובץ חסר. גרמנו לשגיאה הזו בכוונה כשהפעלנו אותו בלי קובץ מפתחות בשום מקום. התיקיה שבסוף השורה היא תיקיית .gmail-mcp בתיקיית הבית שלכם, שעל ה-Mac שלכם נקראת /Users/yourname/.gmail-mcp; שלנו הצביעה על תיקיית טיוטה כדי שהבדיקה לא תוכל לגעת באמיתית. הניחו שם את gcp-oauth.keys.json, או הגדירו את GMAIL_OAUTH_PATH למקום שבו אתם שומרים אותו.
מה רואים
Error: Invalid OAuth keys file format. File should contain either "installed" or "web" credentials.
הפתרון
הקובץ קיים ונקרא כ-JSON תקין, אבל הוא לא הקובץ ש-Google נתנה לכם. גרמנו לשגיאה הזו כשכיוונו את השרת לקובץ שמכיל סוגריים מסולסלים ריקים בלבד. הורדה אמיתית של לקוח OAuth מתחילה במפתח עליון יחיד, installed או web, לפי מה שבחרתם ביצירה, Desktop app או Web application. הורידו אותו שוב מעמוד ה-Credentials במקום לערוך אותו ביד.
מה רואים
Error: Failed to list labels: No access, refresh token, API key or refresh handler callback is set.
הפתרון
זה המצב שבו הייתה ריצת האימות שלנו, ושווה להבין אותו כי הוא נראה כמו שרת תקול והוא לא. קובץ לקוח ה-OAuth רק מספר לשרת מי שואל; האסימון שמעיד ש-Google הסכימה יושב בקובץ שני, credentials.json, שנכתב בפקודת ההתחברות החד-פעמית. הריצו npx @gongrzhe/server-gmail-autoauth-mcp auth, אשרו את הגישה בדפדפן והפעילו מחדש את לקוח ה-MCP. אותה הודעה חוזרת גם אם מחקתם את הקובץ הזה או הוצאתם אותו מהתיקיה שהשרת קורא.
הפתרון
הפקודה npx שייכת ל-Node.js. אם Node לא מותקן על ה-Mac, כל לקוח בעמוד הזה ייכשל בשלב ההפעלה עוד לפני שהשרת מספיק לומר משהו. התקינו Node מ-nodejs.org, הפעילו מחדש את לקוח ה-MCP ונסו שוב.
שאלות נפוצות
זו תוכנה קטנה שנותנת לעוזר AI סדרת פעולות ב-Gmail: חיפוש בתיבה בתחביר החיפוש הרגיל של Gmail, קריאת הודעה, שליחה וניסוח של מייל עם קבצים מצורפים, העברת הודעות בין תוויות, ויצירה או מחיקה של תוויות ומסננים. הוא רץ כתהליך מקומי על ה-Mac שלכם ומדבר עם אפליקציית ה-AI על גבי stdio, מול לקוח OAuth שאתם יוצרים בחשבון Google שלכם. [5][6]
הפעלנו את השרת, השלמנו את לחיצת היד של MCP וקראנו את רשימת הכלים ישירות מהחיבור; החלק הזה נמדד, והטבלה למעלה היא התשובה הגולמית. גם ביצענו קריאת כלי אמיתית אחת, list_email_labels, והיא נכשלה, כי קריאה אמיתית דורשת אסימון של Google לתיבה אמיתית ואין לנו כזה. לכן רשימת הכלים היא ראיה, ושום דבר בעמוד הזה לא מתאר מה מחזירה שאילתת Gmail מוצלחת. השגיאות שכן קיבלנו מודפסות במלואן בקטע פתרון התקלות.
השרת הרץ חושף 19: דואר (send_email, draft_email, read_email, search_emails, modify_email, delete_email), פעולות באצווה (batch_modify_emails, batch_delete_emails), תוויות (list_email_labels, create_label, update_label, delete_label, get_or_create_label), מסננים (create_filter, list_filters, get_filter, delete_filter, create_filter_from_template) וקבצים מצורפים (download_attachment). הטבלה למעלה היא פלט ה-tools/list החי, מילה במילה.
לא נכון לתאריך שבעמוד הזה. חיפשנו כזה תחת המרחבים המתבקשים ב-npm, @google, @google-cloud ו-@googleworkspace, ולא מצאנו דבר, וגם באוסף שרתי הייחוס של פרויקט ה-Model Context Protocol אין שרת Gmail. כל שרת MCP ל-Gmail שאפשר להתקין היום, כולל זה שבעמוד, נבנה על ידי הקהילה. [7]
פעם אחת, כן, ועדיף לומר זאת מאשר להעמיד פנים. החיבור עצמו הוא שלושה שדות ב-Routines, או עריכה קטנה של קובץ JSON ב-Claude Desktop וב-Cursor, אבל לפני כל זה צריך ליצור לקוח OAuth של Google ולהריץ פעם אחת את פקודת ה-auth של החבילה כדי שתשמור אסימון. אין דרך לבצע את ההתחברות הזו מתוך לקוח MCP, כי השרת מצפה שהאסימון כבר יהיה על הדיסק כשהוא עולה. [5][13]
דעו במה אתם בוחרים. מאגר ה-GitHub שמאחורי החבילה נמצא בארכיון, כך ש-38 הסוגיות הפתוחות ו-32 בקשות המשיכה הפתוחות שלו לא יכולות להיפתר במקור. הדחיפה האחרונה אליו הייתה באוגוסט 2025, וגם החבילה ב-npm לא זזה מאז. עדיין כמעט כולם מתקינים דווקא אותה: 36,179 הורדות בשבוע האחרון, מול 1,725 עבור @shinzolabs/gmail-mcp, שאינו בארכיון ועודכן לאחרונה בנובמבר 2025. אם קוד מתוחזק חשוב לכם יותר מקוד פופולרי, זו החלופה שכדאי לבחון. עוד קוריוז ששווה להכיר: npm מציג את החבילה כ-ISC בעוד שקובץ ה-LICENSE במאגר הוא MIT. [3][2][4][8][9]
לא. ל-Routines כבר יש מחבר Gmail שמפעילים בהתחברות בלחיצה אחת, בלי ליצור פרויקט ב-Google Cloud ובלי להניח קובץ מפתחות, והאסימונים שלו נשארים על ה-Mac שלכם. התקינו את שרת הקהילה הזה אם אתם רוצים את מערך הכלים הרחב יותר שלו, ובעיקר את כלי המסננים והאצווה, או אם אתם רוצים את אותה גישה ל-Gmail גם ב-Claude Desktop או ב-Cursor. [13]
מקורות
כל מה שבעמוד הזה שלא ראינו בעצמנו בריצה מקושר כאן, עם התאריך שבו קראנו אותו. לגבי השאר, הריצה עצמה היא הקבלה.
[1]
Latest version 1.1.11, published 2025-08-06. Declares the ISC license and a single maintainer, gongrzhe.
[2]
[3]
1,167 stars, 408 forks, archived, and a last push dated 2025-08-06, per the GitHub API. The 70 open items are 38 issues and 32 pull requests, counted separately through the GitHub search API.
[4]
MIT, copyright 2025 GongRzhe, as reported by the GitHub API for the repository.
[5]
The Google Cloud project and OAuth client steps, the auth command, and the client config shape.
[6]
Instantiates StdioServerTransport, and loads the OAuth key file before registering any handler.
[7]
No Gmail server among the project's own reference servers.
[8]
56 stars, not archived, and a last push dated 2025-11-25, per the GitHub API.
[9]
1,725 downloads for the week ending 2026-08-01.
[10]
The claude_desktop_config.json shape and where the file lives.
[11]
[12]
[13]
The built-in one-click Gmail connector and how Routines runs any MCP server.
העמוד הזה מתאר את Gmail כפי שהתנהג בריצה מתוארכת אחת על Mac אחד. גרסאות משתנות: אם משהו כאן כבר לא תואם למה שאתם רואים, תאריך הלכידה בראש העמוד אומר בן כמה הצילום.
מאחורי המדריך הזה
Routines, האפליקציה שמאחורי המדריך הזה, מריצה שרתי MCP כמו זה בלי טרמינל: כך עובדים המחברים. הפתקים שלכם נשארים קובצי markdown על ה-Mac שלכם, אין חשבון ענן לשלם, והיא עובדת גם בלי אינטרנט. להורדת Routines