| name | gmail-actions |
| description | Execute approved email actions via Gmail MCP server — send replies, drafts, archive. Reads approved email plans from Approved/ folder and executes them. |
Gmail Actions
You execute approved email plans using the Gmail MCP server.
Prerequisites
- Gmail MCP authenticated:
npx @shinzolabs/gmail-mcp auth (one-time setup)
- OAuth credentials at
~/.gmail-mcp/gcp-oauth.keys.json
- Approved email plan in
AI_Employee_Vault/Approved/
Workflow
Step 1: Find Approved Email Plans
Read all .md files in AI_Employee_Vault/Approved/ where frontmatter has type: email.
If none found, report "No approved email actions" and exit.
Step 2: Execute Each Plan
For each approved email plan:
-
Read the plan frontmatter and body
-
Extract: gmail_id, from, subject, and the reply/action content from the body
-
Check DRY_RUN in .env:
- If
DRY_RUN=true: Log what WOULD be done, prefix with [DRY RUN]
- If
DRY_RUN=false: Execute via MCP client
-
Use the MCP client with stdio transport to execute the action:
uv run python .claude/skills/gmail-actions/scripts/mcp-client.py call \
--stdio "gmail-mcp" \
--tool send_message \
--params '{"to": ["<recipient>"], "subject": "<subject>", "body": "<body>"}'
Important notes:
- The transport is stdio (not HTTP). Use
--stdio "gmail-mcp" (globally installed) or --stdio "npx -y @shinzolabs/gmail-mcp"
- The
to field must be an array of email addresses: ["user@example.com"]
- Tool name for sending is
send_message (not send_email)
- Tool name for drafts is
create_draft
- Tool name for replies is
send_message with threadId in params
Available Gmail MCP Tools
| Action | Tool Name | Key Params |
|---|
| Send email | send_message | to (array), subject, body |
| Create draft | create_draft | to (array), subject, body |
| Reply to thread | send_message | to (array), subject, body, threadId |
| Archive | modify_message | id, removeLabelIds: ["INBOX"] |
| Trash | trash_message | id |
| List messages | list_messages | q (search query) |
Step 3: Handle Result
On success:
- Update plan frontmatter:
status: done, add executed: <ISO timestamp>
- Move plan to
AI_Employee_Vault/Done/
- Move associated action file from
In_Progress/ to Done/
On failure:
- Update plan frontmatter:
status: error, add error: <message>
- Leave plan in
Approved/ for retry
- Log error to
AI_Employee_Vault/Logs/
Step 4: Update Dashboard
Update AI_Employee_Vault/Dashboard.md with results.
Step 5: Write Audit Log
Append to AI_Employee_Vault/Logs/YYYY-MM-DD.json:
{
"timestamp": "<ISO 8601>",
"action_type": "email_sent",
"actor": "gmail-actions",
"target": "<plan file>",
"result": "<success|error|dry_run>",
"details": {"to": "<recipient>", "subject": "<subject>"}
}
Output
Report:
- Emails processed: N
- Sent: N
- Errors: N
- Dry run: N
DRY_RUN Mode
When DRY_RUN=true in .env, log all actions but do NOT send any emails. This is the safe default.
Available MCP Tools
See references/gmail-tools.md for the full list of Gmail MCP tools and their parameters.
