remote-mcp-server

This project provides a simple Cloudflare Worker that can fetch unread emails from Gmail using the Gmail API and OAuth 2.0 refresh tokens.

The Worker expects Gmail OAuth credentials to be set as environment variables:

• GMAIL_CLIENT_ID
• GMAIL_CLIENT_SECRET
• GMAIL_REFRESH_TOKEN (This token must have been authorized with the https://www.googleapis.com/auth/gmail.readonly scope or a broader scope that includes read access).

Gmail API Scope Requirements

The GMAIL_REFRESH_TOKEN provided must have been generated with at least the https://www.googleapis.com/auth/gmail.readonly scope to allow the worker to read email messages. If you are using a token with a more restrictive scope (e.g., only for sending), this worker will not be able to fetch emails.

Deploying

1. Install the Cloudflare wrangler CLI and authenticate with your Cloudflare account.
2. Configure the secrets in the Cloudflare dashboard or via wrangler secret put.
3. Deploy the worker:

wrangler deploy

Usage

Send a GET request to the worker's URL to retrieve a list of unread emails.

curl https://<your-worker-url>

The worker will refresh the access token using the stored refresh token and then fetch unread emails via the Gmail API.

The response will be a JSON array of email summaries, for example:

[
  {
    "id": "18f5examplemessageid1",
    "from": "Sender Name <sender@example.com>",
    "date": "Mon, 20 May 2024 10:30:00 +0000",
    "subject": "Example Unread Email",
    "snippet": "This is a snippet of the unread email body..."
  },
  {
    "id": "18f5examplemessageid2",
    "from": "Another Sender <another@example.com>",
    "date": "Mon, 20 May 2024 11:00:00 +0000",
    "subject": "Important Update",
    "snippet": "Please review the attached document regarding the recent update."
  }
]

If there are no unread emails, an empty array [] will be returned.

Integration with a WhatsApp Agent

This Cloudflare Worker can be used as a backend for a WhatsApp agent to periodically fetch and display unread emails. Here's a high-level overview of how such an integration could work:

1. Initiating the Request:

   • The backend of your WhatsApp agent will make an HTTPS GET request to the deployed Cloudflare Worker's URL (e.g., https://remote-mcp-server.your-username.workers.dev).
   • This request can be triggered by a user command in WhatsApp (e.g., "/checkemails") or run on a schedule.

2. Authentication (Recommended Enhancement):

   • For added security, consider protecting your Cloudflare Worker endpoint.
   • One common method is to require a secret token (API key) in a specific header (e.g., X-Custom-Auth-Token) with the request from your WhatsApp agent's backend.
   • Your Cloudflare Worker would then need to be modified to validate this token before processing the request. (Note: This authentication mechanism is not implemented in the current version of this worker and would be an enhancement you'd add.)

3. Receiving the Response:

   • The Cloudflare Worker will respond with a JSON array if successful.
   • Each object in the array represents an unread email and contains the following fields: id, from, date, subject, and snippet.
   • An empty array [] signifies no unread emails.

4. Parsing and Displaying in WhatsApp:

   • Your WhatsApp agent's backend needs to parse this JSON response.
   • Iterate through each email summary object in the array.
   • For each email, format the information (e.g., "From: [sender]\nSubject: [subject]\nSnippet: [snippet]\nDate: [date]") into a user-friendly string.
   • Send these formatted strings as messages to the user in the WhatsApp chat interface. You might want to send each email summary as a separate message or combine them, depending on preference and message length limits.

5. Error Handling by the WhatsApp Agent:

   • The WhatsApp agent's backend should be prepared to handle various error scenarios:
     • Network issues when trying to reach the Cloudflare Worker.
     • Non-200 HTTP status codes from the Cloudflare Worker (e.g., 500 if there's an issue with Gmail API access on the worker's side, 405 if the wrong HTTP method is used).
     • The worker might return an error message in the response body that could be logged or (selectively) relayed.
     • Timeouts if the worker takes too long to respond.
   • Implement appropriate logging and user feedback mechanisms in your WhatsApp agent for these situations (e.g., "Sorry, I couldn't fetch your emails right now. Please try again later.").