Moist

Gmail MCP Connector

"Neither rain nor snow nor stranded tokens shall stay this messenger."

---

Moist is an MCP server that exposes Gmail operations as tools. It handles OAuth 2.0, token refresh, rate limiting, and MIME parsing so consuming applications don't have to.

Quick Start

1. Google Cloud Setup

1. Create a project in the Google Cloud Console
2. Enable the Gmail API
3. Create OAuth 2.0 Client ID credentials (Desktop application type)
4. Add http://localhost:3000/oauth/callback as an authorized redirect URI
5. Note your Client ID and Client Secret

2. MCP Configuration

Add Moist to your MCP client configuration:

{
  "mcpServers": {
    "moist": {
      "command": "npx",
      "args": ["@ticktockbent/moist"],
      "env": {
        "MOIST_CLIENT_ID": "your_client_id",
        "MOIST_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

3. First Run

On the first connection, Moist opens your browser for Google OAuth consent. Once authorized, tokens are encrypted and stored locally at ~/.moist/tokens.json. Subsequent runs authenticate automatically.

Environment Variables

Variable	Required	Description
MOIST_CLIENT_ID	Yes	Google OAuth 2.0 Client ID
MOIST_CLIENT_SECRET	Yes	Google OAuth 2.0 Client Secret
MOIST_REDIRECT_URI	No	OAuth callback URI (default: http://localhost:3000/oauth/callback)

Tools

Authentication

Tool	Description
moist_auth_status	Check authentication state, email, scopes, and token expiry
moist_auth_logout	Revoke tokens and clear stored credentials

Messages

Tool	Description
moist_list_messages	Search and list messages with pagination and label filtering
moist_get_message	Get full message details including body, headers, and attachments
moist_send_message	Send an email (supports replies via replyTo and threading via threadId)
moist_trash_message	Move a message to trash
moist_delete_message	Permanently delete a message (irreversible)

Threads

Tool	Description
moist_list_threads	List threads with search and label filtering
moist_get_thread	Get a thread with all its messages
moist_trash_thread	Move an entire thread to trash

Labels

Tool	Description
moist_list_labels	List all labels (system and user-created)
moist_modify_labels	Add or remove labels from a message

Search

Tool	Description
moist_search	Search messages using Gmail's full query syntax

Gmail search supports operators like from:, to:, subject:, has:attachment, is:unread, is:starred, label:, after:, before:, filename:, and "exact phrases". Operators can be combined:

from:bank@example.com has:attachment after:2024/01/01 subject:statement

Drafts

Tool	Description
moist_create_draft	Create a new draft email
moist_list_drafts	List drafts with pagination
moist_delete_draft	Delete a draft
moist_send_draft	Send an existing draft

Architecture

src/
├── index.ts              # MCP server entry point (stdio transport)
├── types.ts              # TypeScript interfaces
├── auth/
│   ├── oauth.ts          # OAuth 2.0 flow, token refresh, browser consent
│   └── storage.ts        # Encrypted token persistence (~/.moist/)
├── client/
│   ├── gmail.ts          # Gmail API wrapper, MIME parsing, message building
│   └── rate-limiter.ts   # Sliding-window quota tracker
└── tools/
    ├── auth.ts           # Auth status and logout tools
    ├── messages.ts       # Message CRUD tools
    ├── threads.ts        # Thread tools
    ├── labels.ts         # Label tools
    ├── search.ts         # Search tool
    └── drafts.ts         # Draft tools

Key Design Decisions

• Stateless -- No caching. Each tool call hits the Gmail API directly.
• Single account -- One Gmail account per server instance. Run multiple instances for multiple accounts.
• Raw content -- Message bodies are returned as-is (plain text and HTML). No parsing or summarization.
• Encrypted storage -- Tokens at rest are AES-256-CBC encrypted using a machine-specific derived key.
• Rate limiting -- Tracks Gmail API quota usage in a sliding 1-second window (250 units/sec per Google's limits). Returns structured errors with retry timing when exceeded.

Error Handling

All tools return consistent error shapes:

{
  "error": "not_found",
  "message": "Human-readable description",
  "details": {}
}

Error Code	Meaning
not_found	Message, thread, or label doesn't exist
rate_limited	Gmail API quota exceeded (includes retryAfter)
auth_failed	Token expired or revoked
invalid_request	Bad parameters
api_error	Gmail API error (details included)

OAuth Scopes

Moist requests these scopes during authorization:

Scope	Purpose
gmail.readonly	Read messages, threads, and labels
gmail.send	Send messages
gmail.modify	Modify labels, trash/untrash
gmail.compose	Create and manage drafts

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

License

MIT

References

• Gmail API Documentation
• MCP Specification
• Going Postal -- The source of the name