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.

Related MCP server: Gmail MCP Server

Environment Variables

Tools

Authentication

Messages

Threads

Labels

Search

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

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": {}
}

OAuth Scopes

Moist requests these scopes during authorization:

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