Wiring Gmail into OpenClaw

Dear Readers,

credentials are sorted. Now we connect Gmail to OpenClaw through MCP — the protocol that gives agents access to external tools without baking API calls into the model itself.

MCP in 30 Seconds

#

Model Context Protocol is a standard for connecting AI models to external capabilities. Instead of the agent making raw HTTP requests, it calls named tools (like gmail_search or gmail_create_draft) through an MCP server that handles authentication and API translation.

The architecture looks like this:

User (Telegram) → OpenClaw Gateway → Claude → MCP Server → Gmail API

Claude never sees your OAuth tokens. It calls a tool by name, the MCP server handles the rest, and results come back as structured data. This separation matters — the model can’t leak credentials it never had.

Installing the Gmail MCP Server

#

The Gmail MCP server runs as an npx package. No global install needed — OpenClaw spawns it on demand:

# Test that it runs (will fail without config, but confirms the package exists)
npx @anthropic/gmail-mcp-server --help

Gotcha: The first npx invocation downloads the package and its dependencies. On ARM64 this can take 10-15 seconds, which may cause OpenClaw to time out on the first tool call. Run it once manually to prime the npm cache.

Agent Configuration

#

Here’s the full agent config for the email agent. Add this to your OpenClaw agents config:

// openclaw agents config
{
  "id": "email",
  "name": "Email Agent",
  "workspace": "/root/openclaw/email-workspace",
  "model": "anthropic/claude-sonnet-4-6",
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@anthropic/gmail-mcp-server",
        "--credentials-file", "/root/openclaw/gmail-credentials.json",
        "--token-file", "/root/openclaw/gmail-tokens.json"
      ]
    }
  }
}

A few decisions here:

• Separate workspace — the email agent gets its own workspace directory, isolated from the PA agent’s Obsidian vault. This keeps the SOUL.md files separate.
• Sonnet over Haiku — email requires more nuanced reasoning than note-taking. Summarizing threads, understanding tone, drafting contextual replies. Sonnet handles this better.
• Explicit token path — keeping tokens in the openclaw directory rather than the default ~/.gmail-mcp/ location makes backups and permissions easier to manage.

Available Tools

#

Once connected, the agent gets access to these tools:

Notice what’s missing: no gmail_send, no gmail_delete, no gmail_modify. The OAuth scopes from the previous post prevent these from existing at the API level, and the MCP server doesn’t expose them either.

Tool Filtering

#

Even within the available tools, you might want to restrict further. OpenClaw supports tool whitelisting at the agent level:

{
  "id": "email",
  "name": "Email Agent",
  "allowedTools": [
    "gmail_list_messages",
    "gmail_get_message",
    "gmail_search",
    "gmail_create_draft",
    "gmail_get_thread"
  ],
  "mcpServers": {
    "gmail": { "..." : "..." }
  }
}

This removes gmail_list_drafts, gmail_get_draft, and gmail_list_labels from the agent’s available tools. Not because they’re dangerous — they’re read-only — but because fewer tools means less confusion for the model. An agent that can do five things well beats one that fumbles through eight.

Create the Workspace

#

Set up the email agent’s workspace directory:

mkdir -p /root/openclaw/email-workspace

We’ll add a SOUL.md here in the next post. For now, create a minimal one:

# /root/openclaw/email-workspace/SOUL.md
echo "You are an email assistant. Read emails and create drafts. Never send emails directly." \
  > /root/openclaw/email-workspace/SOUL.md

Testing via Telegram

#

Restart the gateway to pick up the new agent:

systemctl --user restart openclaw-gateway

Then send a message in Telegram specifying the email agent:

@email What are my most recent unread emails?

If everything’s wired correctly, you’ll get back a summary of your latest messages. The first call might be slow (npx cold start), but subsequent calls should respond in a few seconds.

Gotcha: If you get authentication errors, the token file might not exist yet. Run the MCP server manually once to complete the OAuth flow:

npx @anthropic/gmail-mcp-server \
  --credentials-file /root/openclaw/gmail-credentials.json \
  --token-file /root/openclaw/gmail-tokens.json \
  --auth

This opens the Google consent screen, you approve, and the token file gets created. After that, the agent handles token refresh automatically.

Where We Stand

#

The email agent can now:

1. Read your inbox via Telegram
2. Search for specific emails
3. Read full threads
4. Create draft replies

It cannot send, delete, or modify anything. We’ve got two layers of protection in place — OAuth scopes and MCP tool filtering. In the next post, we’ll add a third: a purpose-built SOUL.md that defines exactly how the agent should behave with email.

Next up: Writing a SOUL.md for Email