ClaudePost MCP Server: Secure Gmail Search, Read, Send

Overview

ClaudePost MCP Server is a small Model Context Protocol (MCP) server that connects an LLM-based agent to a user’s Gmail account in a privacy-conscious way. It implements a set of MCP “tools” that let an LLM search mail, fetch message content, and send replies without giving the model indiscriminate access to your entire mailbox. The server mediates OAuth authentication, enforces scopes, and provides explicit tool inputs and outputs so downstream agents can operate with clearer intent and auditability.

This pattern is useful when you want an LLM to act on email (summarize, triage, draft replies, or extract structured data) but need to keep control over which actions are performed and which parts of messages are exposed. Running a dedicated MCP server local to you or within a trusted environment reduces shared token exposure and makes it easier to log, monitor, and restrict how models interact with Gmail.

Features

• Exposes Gmail operations as MCP tools: search, read, and send
• OAuth-based authentication using Gmail API scopes (user consent)
• Fine-grained privacy controls: limit scopes and message fields the model can see
• Tool manifests compatible with MCP-enabled LLM agents
• Local-first design suitable for self-hosting (Docker or node installs)
• Simple JSON-based request/response shapes for easy integration

Installation / Configuration

Clone and run the project, or use Docker for a containerized run.

Clone repository:

git clone https://github.com/ZilongXue/claude-post.git
cd claude-post

Install and run (Node example):

# install dependencies
npm install

# build (if project uses TypeScript)
npm run build

# start
npm start

Docker:

# build image
docker build -t claudepost-mcp .

# run container (example)
docker run -p 3000:3000 \
  -e PORT=3000 \
  -e BASE_URL="https://your-host.example" \
  -e GOOGLE_CLIENT_ID="..." \
  -e GOOGLE_CLIENT_SECRET="..." \
  -e SESSION_SECRET="supersecret" \
  claudepost-mcp

Recommended environment variables

OAuth setup (high level)

1. Create OAuth credentials in Google Cloud Console.
2. Add redirect URI: BASE_URL + /auth/callback (or follow server documentation).
3. Request only the scopes needed, e.g.:
   • https://www.googleapis.com/auth/gmail.readonly (read/search)
   • https://www.googleapis.com/auth/gmail.send (send only)
   • or https://mail.google.com/ for full mailbox access (not recommended)

Security tips

• Prefer least privilege in OAuth scopes.
• Run the server in a trusted environment.
• Use HTTPS for BASE_URL and secure SESSION_SECRET.
• Rotate credentials and limit token persistence duration.

Available Tools

The server exposes a small set of MCP-style tools that an LLM agent can call. Typical tool names and inputs:

1. gmail.search

   • Purpose: Find messages matching query and return lightweight metadata.
   • Input: { “query”: “from:alice subject:invoice”, “max_results”: 10 }
   • Output: list of message summaries (id, threadId, snippet, labels, date)

2. gmail.read

   • Purpose: Fetch full or partial content of one message by id.
   • Input: { “message_id”: “…”, “parts”: [“subject”,“from”,“body_plain”] }
   • Output: requested fields (plain text body, headers, attachments metadata)

3. gmail.send

   • Purpose: Send a composed message or draft reply.
   • Input: { “to”: “…”, “subject”: “…”, “body”: “…”, “in_reply_to”: “messageId” }
   • Output: send status and sent message id

Example MCP manifest snippet (JSON):

{
  "tools": [
    {
      "name": "gmail.search",
      "description": "Search Gmail and return summaries.",
      "input_schema": { "type": "object", "properties": { "query": { "type": "string" } } }
    },
    {
      "name": "gmail.read",
      "description": "Read a specific Gmail message.",
      "input_schema": { "type": "object", "properties": { "message_id": { "type": "string" } } }
    },
    {
      "name": "gmail.send",
      "description": "Send an email through Gmail.",
      "input_schema": { "type": "object", "properties": { "to": { "type": "string" }, "body": { "type": "string" } } }
    }
  ]
}

Example cURL: search

curl -X POST "https://your-server.example/mcp/run/gmail.search" \
  -H "Content-Type: application/json" \
  -d '{"query":"label:unread subject:invoice","max_results":5}'

Use Cases

• Inbox triage automated by an LLM: run gmail.search for “invoices” and ask the model to extract vendor, amount, due date from each message using gmail.read for matched IDs.
• Draft replies and send: compose a reply with gmail.read (to include quoted context) and confirm via human review before gmail.send is invoked.
• Summarization of threads: collect messages in a thread and ask the model to produce a short summary and action items.
• Monitoring and notifications: search for messages matching alerts and send templated acknowledgements automatically.

Additional Resources

• GitHub: https://github.com/ZilongXue/claude-post
• Google OAuth & Gmail API docs:
  • https://developers.google.com/identity
  • https://developers.google.com/gmail/api
• Model Context Protocol (MCP) concepts: look for tool manifest patterns and JSON tool call schemas used by your LLM integration framework.

This server is intended to be a minimal, auditable bridge between LLM agents and Gmail. Review and adapt OAuth scopes, session handling, and token storage to meet your security and privacy requirements.