gmail-mcp-imap 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suhail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,168 @@
+# gmail-mcp-imap
+
+A Gmail MCP (Model Context Protocol) server that provides email management capabilities through IMAP/SMTP. Works with Claude Desktop, Claude Code, and any MCP-compatible client.
+
+## Features
+
+- **Gmail Categories**: Fetch emails by Gmail's smart categories (Primary, Social, Promotions, Updates, Forums)
+- **Full Email Management**: Read, send, reply, star, delete, and label emails
+- **Attachment Handling**: List, download, and save attachments to disk
+- **No Google API Required**: Uses IMAP/SMTP directly with App Password authentication
+- **Date Filtering**: Filter emails by date range
+
+## Installation
+
+```bash
+npm install gmail-mcp-imap
+```
+
+Or run directly with npx:
+
+```bash
+npx gmail-mcp-imap
+```
+
+## Prerequisites
+
+1. A Gmail account
+2. **App Password** (not your regular password):
+   - Go to [Google Account Security](https://myaccount.google.com/security)
+   - Enable 2-Step Verification if not already enabled
+   - Go to App Passwords (search for "App Passwords" in account settings)
+   - Generate a new app password for "Mail"
+   - Copy the 16-character password
+
+## Configuration
+
+### Environment Variables
+
+Set these environment variables before running:
+
+```bash
+export GMAIL_EMAIL="your-email@gmail.com"
+export GMAIL_APP_PASSWORD="your-16-char-app-password"
+```
+
+### Claude Desktop Configuration
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "npx",
+      "args": ["gmail-mcp-imap"],
+      "env": {
+        "GMAIL_EMAIL": "your-email@gmail.com",
+        "GMAIL_APP_PASSWORD": "your-app-password"
+      }
+    }
+  }
+}
+```
+
+### Claude Code Configuration
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "gmail": {
+      "command": "npx",
+      "args": ["gmail-mcp-imap"],
+      "env": {
+        "GMAIL_EMAIL": "your-email@gmail.com",
+        "GMAIL_APP_PASSWORD": "your-app-password"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### Category Tools
+| Tool | Description |
+|------|-------------|
+| `get_primary_emails` | Important conversations from real people |
+| `get_social_emails` | Social network notifications |
+| `get_promotions_emails` | Marketing emails, deals, offers |
+| `get_updates_emails` | Receipts, bills, statements |
+| `get_forums_emails` | Mailing lists, discussion groups |
+
+### Search & Read Tools
+| Tool | Description |
+|------|-------------|
+| `search_emails` | Search emails by keywords |
+| `get_email_content` | Get full email content by UID |
+| `get_emails_by_label` | Get emails from a specific label |
+| `list_labels` | List all Gmail labels/folders |
+
+### Action Tools
+| Tool | Description |
+|------|-------------|
+| `send_email` | Send a new email |
+| `reply_to_email` | Reply to an existing email |
+| `mark_as_read` | Mark email as read |
+| `mark_as_unread` | Mark email as unread |
+| `star_email` | Star or unstar an email |
+| `delete_email` | Move email to trash |
+| `apply_label` | Apply a label to an email |
+
+### Attachment Tools
+| Tool | Description |
+|------|-------------|
+| `list_attachments` | List attachments in an email |
+| `download_attachment` | Download attachment as Base64 |
+| `save_attachment` | Save attachment to disk |
+
+## Usage Examples
+
+Once configured, you can ask Claude:
+
+- "Show me my primary emails from the last week"
+- "Search for emails from Amazon"
+- "Read the email with UID 12345"
+- "Send an email to john@example.com about the meeting"
+- "Download the PDF attachment from email 12345"
+- "Star the important emails about invoices"
+
+## Why IMAP/SMTP?
+
+This MCP server uses IMAP/SMTP instead of the Google API because:
+
+1. **Simpler Setup**: No OAuth consent screen or API credentials needed
+2. **App Passwords**: More secure than storing your main password
+3. **No Rate Limits**: Google API has strict quotas; IMAP doesn't
+4. **Works Offline**: No dependency on Google's API servers
+5. **Privacy**: Your emails aren't processed through additional Google services
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/suhailak/gmail-mcp.git
+cd gmail-mcp
+
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Build for production
+npm run build
+
+# Run production build
+npm start
+```
+
+## License
+
+MIT
+
+## Author
+
+Suhail ([@ansuhail.ak@gmail.com](mailto:ansuhail.ak@gmail.com))

package/build/gmail-client.d.ts

@@ -0,0 +1,78 @@
+declare const GMAIL_CATEGORIES: readonly ["primary", "social", "promotions", "updates", "forums"];
+type GmailCategory = (typeof GMAIL_CATEGORIES)[number];
+export interface EmailMessage {
+    id: string;
+    uid: number;
+    subject: string;
+    from: string;
+    to: string;
+    date: string;
+    snippet: string;
+    labels: string[];
+    isRead: boolean;
+    isStarred: boolean;
+}
+export interface EmailContent extends EmailMessage {
+    body: string;
+    attachments: Array<{
+        filename: string;
+        contentType: string;
+        size: number;
+    }>;
+}
+export interface AttachmentData {
+    filename: string;
+    contentType: string;
+    size: number;
+    content: string;
+}
+export interface GmailConfig {
+    email: string;
+    appPassword: string;
+}
+export declare class GmailClient {
+    private config;
+    private smtpTransport;
+    constructor(config: GmailConfig);
+    private createImapConnection;
+    private getSmtpTransport;
+    private runImapOperation;
+    getEmailsByCategory(category: GmailCategory, limit?: number, dateFilter?: {
+        after?: string;
+        before?: string;
+    }): Promise<EmailMessage[]>;
+    getEmailsByLabel(label: string, limit?: number): Promise<EmailMessage[]>;
+    searchEmails(query: string, limit?: number): Promise<EmailMessage[]>;
+    getEmailContent(uid: number): Promise<EmailContent | null>;
+    listLabels(): Promise<string[]>;
+    sendEmail(to: string, subject: string, body: string, options?: {
+        cc?: string;
+        bcc?: string;
+        html?: boolean;
+        replyTo?: string;
+    }): Promise<{
+        success: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+    replyEmail(uid: number, body: string, options?: {
+        html?: boolean;
+    }): Promise<{
+        success: boolean;
+        messageId?: string;
+        error?: string;
+    }>;
+    markAsRead(uid: number, read?: boolean): Promise<boolean>;
+    starEmail(uid: number, starred?: boolean): Promise<boolean>;
+    deleteEmail(uid: number): Promise<boolean>;
+    applyLabel(uid: number, label: string): Promise<boolean>;
+    downloadAttachment(uid: number, filename: string): Promise<AttachmentData | null>;
+    listAttachments(uid: number): Promise<Array<{
+        filename: string;
+        contentType: string;
+        size: number;
+    }>>;
+    disconnect(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=gmail-client.d.ts.map

package/build/gmail-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gmail-client.d.ts","sourceRoot":"","sources":["../src/gmail-client.ts"],"names":[],"mappings":"AAMA,QAAA,MAAM,gBAAgB,mEAAoE,CAAC;AAC3F,KAAK,aAAa,GAAG,CAAC,OAAO,gBAAgB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAa,SAAQ,YAAY;IAChD,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,KAAK,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,aAAa,CAA4B;gBAErC,MAAM,EAAE,WAAW;IAK/B,OAAO,CAAC,oBAAoB;IAY5B,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,gBAAgB;IAmBlB,mBAAmB,CACvB,QAAQ,EAAE,aAAa,EACvB,KAAK,GAAE,MAAW,EAClB,UAAU,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/C,OAAO,CAAC,YAAY,EAAE,CAAC;IA+FpB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAsF5E,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;IAoFxE,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC;IAsE1D,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IA4B/B,SAAS,CACb,EAAE,EAAE,MAAM,EACV,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QACR,EAAE,CAAC,EAAE,MAAM,CAAC;QACZ,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,GACA,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IA8B9D,UAAU,CACd,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,GAC3B,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAqB9D,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,OAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAuB/D,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,OAAc,GAAG,OAAO,CAAC,OAAO,CAAC;IAuBjE,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsB1C,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAsBxD,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IA0DjF,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAkDrG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;CAMlC"}