Moist

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