一个模型上下文协议 (MCP) 服务器，提供与 Gmail 和日历 API 交互的工具。此服务器可让您通过 MCP 界面以编程方式管理电子邮件和日历活动。
list_emails ：列出收件箱中最近的电子邮件，并可选择过滤
search_emails ：使用 Gmail 查询语法进行高级电子邮件搜索
send_email ：发送新邮件，支持抄送和密送
modify_email ：修改电子邮件标签（存档、垃圾箱、标记为已读/未读）
list_events ：列出即将发生的日历事件，并按日期范围进行过滤
create_event ：创建有参与者的新日历事件
update_event ：更新现有日历事件
delete_event ：删除日历事件
Related MCP server: Gmail AutoAuth MCP Server
Node.js ：安装 Node.js 版本 14 或更高版本
Google Cloud 控制台设置：
创建新项目或选择现有项目
启用 Gmail API 和 Google 日历 API：
前往“API 和服务”>“库”
搜索并启用“Gmail API”
搜索并启用“Google 日历 API”
设置 OAuth 2.0 凭据：
前往“API 和服务”>“凭证”
点击“创建凭证”>“OAuth 客户端 ID”
选择“Web应用程序”
将“授权重定向 URI”设置为包含： http://localhost:4100/code
记下客户端 ID 和客户端密钥
要通过Smithery自动为 Claude Desktop 安装 gsuite-mcp：
npx -y @smithery/cli install @rishipradeep-think41/gsuite-mcp --client claude克隆并安装：
git clone https://github.com/epaproditus/google-workspace-mcp-server.git
cd google-workspace-mcp-server
npm install创建 OAuth 凭证：在根目录中创建一个credentials.json文件：
{
"web": {
"client_id": "YOUR_CLIENT_ID",
"client_secret": "YOUR_CLIENT_SECRET",
"redirect_uris": ["http://localhost:4100/code"],
"auth_uri": "https://accounts.google.com/o/oauth2/auth",
"token_uri": "https://oauth2.googleapis.com/token"
}
}获取刷新令牌：
node get-refresh-token.js这将：
打开浏览器进行 Google OAuth 身份验证
请求以下权限：
https://www.googleapis.com/auth/gmail.modify
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/gmail.send
将凭证保存到token.json
在控制台中显示刷新令牌
配置 MCP 设置：将服务器配置添加到您的 MCP 设置文件：
对于 VSCode Claude 扩展： ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
对于 Claude 桌面应用程序： ~/Library/Application Support/Claude/claude_desktop_config.json
将其添加到mcpServers对象：
{
"mcpServers": {
"google-workspace": {
"command": "node",
"args": ["/path/to/google-workspace-server/build/index.js"],
"env": {
"GOOGLE_CLIENT_ID": "your_client_id",
"GOOGLE_CLIENT_SECRET": "your_client_secret",
"GOOGLE_REFRESH_TOKEN": "your_refresh_token"
}
}
}
}构建并运行：
npm run build列出最近的电子邮件：
{
"maxResults": 5,
"query": "is:unread"
}搜索电子邮件：
{
"query": "from:example@gmail.com has:attachment",
"maxResults": 10
}发送电子邮件：
{
"to": "recipient@example.com",
"subject": "Hello",
"body": "Message content",
"cc": "cc@example.com",
"bcc": "bcc@example.com"
}修改邮箱：
{
"id": "message_id",
"addLabels": ["UNREAD"],
"removeLabels": ["INBOX"]
}列出事件：
{
"maxResults": 10,
"timeMin": "2024-01-01T00:00:00Z",
"timeMax": "2024-12-31T23:59:59Z"
}创建事件：
{
"summary": "Team Meeting",
"location": "Conference Room",
"description": "Weekly sync-up",
"start": "2024-01-24T10:00:00Z",
"end": "2024-01-24T11:00:00Z",
"attendees": ["colleague@example.com"]
}更新事件：
{
"eventId": "event_id",
"summary": "Updated Meeting Title",
"location": "Virtual",
"start": "2024-01-24T11:00:00Z",
"end": "2024-01-24T12:00:00Z"
}删除事件：
{
"eventId": "event_id"
}身份验证问题：
确保所有必需的 OAuth 范围都已授予
验证客户端ID和密钥是否正确
检查刷新令牌是否有效
API 错误：
检查 Google Cloud Console 的 API 配额和限制
确保您的项目已启用 API
验证请求参数是否符合所需格式
该项目已获得 MIT 许可。
Create a new calendar event
| Name | Required | Description | Default |
|---|---|---|---|
| attendees | No | List of attendee email addresses | |
| description | No | Event description | |
| end | Yes | End time in ISO format | |
| location | No | Event location | |
| start | Yes | Start time in ISO format | |
| summary | Yes | Event title |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden of behavioral disclosure. It only states 'create', which implies mutation, but omits details like authorization requirements (e.g., calendar write access), side effects (e.g., notifications to attendees), or whether the event is created immediately. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no extraneous words, which is concise. However, it is too minimal and does not fully earn its place by providing additional context. It could include a brief note on required fields or behavior without significant length increase.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (6 parameters, no output schema, no annotations), the description is incomplete. It does not specify return values (e.g., created event ID), constraints (e.g., title length, time range), or error conditions. An agent would lack critical context for successful invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's property descriptions (e.g., 'Start time in ISO format' already in schema). It does not clarify relationships between parameters or provide usage hints beyond what the schema offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a new calendar event', specifying the verb 'create' and resource 'calendar event'. It distinguishes from sibling tools like 'update_event' and 'delete_event', which modify or remove existing events. However, it could be more precise about the scope (e.g., single event creation with required fields).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'update_event' for modifications or 'list_events' for viewing. The description lacks context about prerequisites or typical scenarios, leaving the agent without decision-making support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a calendar event
| Name | Required | Description | Default |
|---|---|---|---|
| eventId | Yes | Event ID to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states the action. It does not disclose side effects (e.g., irreversible deletion), permission requirements, or behavior for recurring events.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with no wasted words, placed at the beginning of the tool definition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is adequate but lacks context on return values, error conditions, or confirmation. It meets minimum viability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with one parameter eventId described as 'Event ID to delete'. The description adds no extra meaning beyond the schema, earning a baseline of 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Delete a calendar event' clearly states the verb (Delete) and resource (calendar event), distinguishing it from siblings like create_event, update_event, and list_events.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as prerequisites, error handling, or when not to use it (e.g., recurring events).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List recent emails from Gmail inbox
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of emails to return (default: 10) | |
| query | No | Search query to filter emails |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states 'list recent emails', omitting crucial details such as required authentication, rate limits, output format (e.g., headers vs full content), and potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no wasted words. However, it omits important details that could be included without much expansion, slightly reducing its efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the sibling tools (especially 'search_emails'), the description fails to clarify when to use this tool versus searching. It also lacks return value details, pagination, and recency definition, making it incomplete for a tool with no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with both parameters described ('query' for filtering, 'maxResults' with default). The description adds no additional meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List recent emails from Gmail inbox', specifying the verb and resource. However, the term 'recent' is vague, and there is no differentiation from the sibling tool 'search_emails' which likely supports similar queries.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing recent emails but does not provide explicit guidance on when to use this tool versus alternatives like 'search_emails' or 'modify_email'. No context on prerequisites or limitations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List upcoming calendar events
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of events to return (default: 10) | |
| timeMax | No | End time in ISO format | |
| timeMin | No | Start time in ISO format (default: now) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description bears full responsibility for behavioral disclosure. It fails to mention sorting order, inclusion of canceled events, pagination behavior, or default time range behavior beyond implying 'upcoming'. The schema covers parameters but not runtime behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no unnecessary words. However, it omits important behavioral context, so it is not perfectly concise for a helpful description. Still, it is efficiently brief.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description could have explained the return format or common use cases. It also fails to mention that timeMin can be set in the past, contradicting 'upcoming'. The tool is simple but the description lacks completeness for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema, but since the schema is sufficient, this score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'List upcoming calendar events' clearly states the action (list) and resource (calendar events). However, 'upcoming' may be misleading since the tool can list events in any time range via parameters. It distinguishes from siblings implicitly as there is no other event list tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like create_event, update_event, or delete_event. The description does not indicate that this is a read-only operation or that for email lists one should use list_emails.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Modify email labels (archive, trash, mark read/unread)
| Name | Required | Description | Default |
|---|---|---|---|
| addLabels | No | Labels to add | |
| id | Yes | Email ID | |
| removeLabels | No | Labels to remove |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but only states 'Modify email labels' without disclosing side effects, idempotency, exact label behavior (e.g., archive meaning removing INBOX), or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence, front-loaded with the action, no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple mutation tool with 3 params and no output schema; covers the main purpose but lacks detail on error handling or return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, and the description adds value by giving concrete label examples (archive, trash, mark read/unread) beyond the generic schema descriptions, though exact label names are not specified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool modifies email labels, with concrete examples (archive, trash, mark read/unread), distinguishing it from sibling tools like list_emails or send_email.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings (e.g., list_emails or search_emails) or any prerequisites, leaving the agent to infer usage context without support.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search emails with advanced query
| Name | Required | Description | Default |
|---|---|---|---|
| maxResults | No | Maximum number of emails to return (default: 10) | |
| query | Yes | Gmail search query (e.g., "from:example@gmail.com has:attachment"). Examples: - "from:alice@example.com" (Emails from Alice) - "to:bob@example.com" (Emails sent to Bob) - "subject:Meeting Update" (Emails with "Meeting Update" in the subject) - "has:attachment filename:pdf" (Emails with PDF attachments) - "after:2024/01/01 before:2024/02/01" (Emails between specific dates) - "is:unread" (Unread emails) - "from:@company.com has:attachment" (Emails from a company domain with attachments) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool searches emails but doesn't mention whether this is a read-only operation, if it requires specific permissions, how results are returned (e.g., pagination), or any rate limits. The description adds minimal behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Search emails with advanced query'). It avoids redundancy and wastes no words, making it highly concise and well-structured for quick understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (search with query parameters), no annotations, and no output schema, the description is minimally adequate. It covers the basic action but lacks details on behavioral traits, usage context, and return values, leaving gaps that could hinder an agent's effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with detailed examples for the 'query' parameter and a clear description for 'maxResults'. The description adds no additional parameter semantics beyond what the schema provides, so it meets the baseline of 3 for adequate coverage without extra value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'Search emails with advanced query', which specifies the verb (search) and resource (emails). It distinguishes from siblings like 'list_emails' by emphasizing 'advanced query' capabilities, though it doesn't explicitly contrast with 'list_emails' which might be a simpler listing tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'list_emails' or 'modify_email'. It mentions 'advanced query' but doesn't specify scenarios where this is preferred over simpler tools or when not to use it, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Send a new email
| Name | Required | Description | Default |
|---|---|---|---|
| bcc | No | BCC recipients (comma-separated) | |
| body | Yes | Email body (can include HTML) | |
| cc | No | CC recipients (comma-separated) | |
| subject | Yes | Email subject | |
| to | Yes | Recipient email address |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description lacks disclosure of side effects (e.g., sending is a write operation) or other behaviors like authentication, rate limits, or delivery guarantees. Since no annotations are present, the description carries full burden but fails to inform beyond the obvious.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is minimal (one sentence), which is concise but not well-structured. It lacks front-loading of key information and does not earn its brevity by covering essential details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description does not explain return values or error states. For a tool with 5 parameters and no nested objects, more context about the sending process (e.g., confirmation, async) would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear parameter descriptions. The tool description adds no additional meaning beyond what is already in the schema, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Send a new email' clearly identifies the action (send) and resource (email), distinguishing it from siblings like list_emails, modify_email, and search_emails. However, 'new' adds minor value; overall it is clear but not exceptionally specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as modify_email (which might handle drafts or edits). There is no mention of prerequisites, limitations, or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update an existing calendar event
| Name | Required | Description | Default |
|---|---|---|---|
| attendees | No | New list of attendee email addresses | |
| description | No | New event description | |
| end | No | New end time in ISO format | |
| eventId | Yes | Event ID to update | |
| location | No | New event location | |
| start | No | New start time in ISO format | |
| summary | No | New event title |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It implies mutation but doesn't clarify partial vs. full update, permission requirements, side effects, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no wasted words, but slightly under-specified. Could benefit from a brief second sentence on partial update behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 7 parameters and no output schema, the description fails to explain return value (e.g., updated event object) or partial update semantics. Contextually incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for all 7 parameters. The description adds no additional semantics beyond the schema, meeting baseline but not exceeding it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Update an existing calendar event' clearly states the verb (update) and resource (calendar event), and distinguishes from siblings like create_event and delete_event.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., create_event for new events, list_events to find IDs). No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0create_eventdelete_eventlist_emailslist_eventsmodify_emailsearch_emailssend_emailupdate_eventScored across 8 tools
Every tool has a clearly distinct purpose with no ambiguity. Calendar tools (create_event, delete_event, list_events, update_event) and email tools (list_emails, modify_email, search_emails, send_email) are cleanly separated by resource type and action, making misselection unlikely.
All tools follow a consistent verb_noun pattern with snake_case throughout. The naming is predictable and readable, with clear action verbs (create, delete, list, modify, search, send, update) paired with appropriate nouns (event, emails).
With 8 tools, this server is well-scoped for Google Workspace functionality. The count is appropriate, covering core calendar and email operations without being overwhelming or too sparse, with each tool earning its place.
The tool surface provides good coverage for calendar and email workflows, with CRUD operations for events and key email actions. Minor gaps exist, such as no direct email deletion tool (though modify_email handles archiving/trashing) and no calendar search, but agents can work around these.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
Email inboxes and calendars for AI agents: send, receive, search, draft and schedule.
