@marlinjai/email-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marlinjai
+
+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,211 @@
+# @marlinjai/email-mcp
+
+A unified MCP server for email access across Gmail, Outlook, iCloud, and generic IMAP providers.
+
+## Features
+
+- **Multi-provider support** -- Gmail (REST API), Outlook (Microsoft Graph), iCloud (IMAP), and generic IMAP/SMTP
+- **OAuth2 authentication** -- Browser-based OAuth flows for Gmail and Outlook, with automatic token refresh
+- **Full email client** -- Search, read, send, reply, forward, organize, and manage drafts
+- **Batch operations** -- Delete, move, or mark hundreds of emails in a single call
+- **Lightweight search** -- Compact search results by default (~20KB vs ~1.4MB) with optional full body retrieval
+- **Encrypted credential storage** -- AES-256-GCM encryption at rest with machine-derived keys
+- **Provider-native APIs** -- Uses Gmail API and Microsoft Graph where available for richer features, falls back to IMAP for universal compatibility
+
+## Installation
+
+Install globally from npm:
+
+```bash
+npm install -g @marlinjai/email-mcp
+```
+
+Or run directly with npx (no install needed):
+
+```bash
+npx @marlinjai/email-mcp
+```
+
+## Quick Start
+
+1. Run the interactive setup wizard to add your email accounts:
+
+```bash
+npx @marlinjai/email-mcp setup
+```
+
+The wizard will walk you through provider selection and authentication. After each account, it asks if you'd like to add another — so you can set up Gmail, Outlook, and iCloud all in one go.
+
+2. Add the server to your MCP configuration (`.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "email": {
+      "command": "npx",
+      "args": ["@marlinjai/email-mcp"]
+    }
+  }
+}
+```
+
+3. Start using email tools in Claude Code — search your inbox, send emails, organize messages, and more.
+
+## Provider Setup Guides
+
+### Gmail
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/).
+2. Create a new project (or select an existing one).
+3. Enable the **Gmail API** under APIs & Services.
+4. Go to **Credentials** and create an **OAuth 2.0 Client ID** (Desktop application type).
+5. Run the setup wizard:
+
+```bash
+npx @marlinjai/email-mcp setup
+# Select "Gmail" when prompted
+# A browser window will open for authorization
+# Grant the requested permissions and return to the terminal
+```
+
+### Outlook
+
+1. Go to the [Azure Portal](https://portal.azure.com/) and navigate to **App registrations**.
+2. Register a new application (select "Personal Microsoft accounts" for consumer Outlook).
+3. Under **Authentication**, add a redirect URI for `http://localhost`.
+4. Under **API permissions**, add `Mail.ReadWrite`, `Mail.Send`, and `offline_access`.
+5. Run the setup wizard:
+
+```bash
+npx @marlinjai/email-mcp setup
+# Select "Outlook" when prompted
+# A browser window will open for authorization
+# Sign in and grant the requested permissions
+```
+
+### iCloud
+
+1. Go to [appleid.apple.com](https://appleid.apple.com/) and sign in.
+2. Navigate to **App-Specific Passwords** and generate a new password.
+3. Run the setup wizard:
+
+```bash
+npx @marlinjai/email-mcp setup
+# Select "iCloud" when prompted
+# Enter your iCloud email address
+# Enter the app-specific password you generated
+```
+
+### Generic IMAP
+
+Run the setup wizard with your IMAP/SMTP server details:
+
+```bash
+npx @marlinjai/email-mcp setup
+# Select "Other IMAP" when prompted
+# Enter your IMAP host, port, and credentials
+# Optionally enter SMTP host and port for sending
+```
+
+## Available Tools (24)
+
+### Account Management (4)
+
+| Tool | Description |
+|------|-------------|
+| `email_list_accounts` | List all configured accounts with connection status |
+| `email_add_account` | Add a new IMAP or iCloud account (Gmail/Outlook require setup wizard) |
+| `email_remove_account` | Remove an account and its stored credentials |
+| `email_test_account` | Test connection to an account |
+
+### Reading & Searching (5)
+
+| Tool | Description |
+|------|-------------|
+| `email_list_folders` | List all folders/labels for an account |
+| `email_search` | Search emails with filters. Returns compact results by default (`returnBody=false`). Set `returnBody=true` to include full email bodies |
+| `email_get` | Get full email content by ID (headers, body, attachment metadata) |
+| `email_get_thread` | Get an entire email thread/conversation |
+| `email_get_attachment` | Download a specific attachment by ID (returns base64 data) |
+
+### Sending & Drafts (5)
+
+| Tool | Description |
+|------|-------------|
+| `email_send` | Compose and send a new email (to, cc, bcc, subject, body) |
+| `email_reply` | Reply to an email (supports reply-all, preserves threading) |
+| `email_forward` | Forward an email to new recipients |
+| `email_draft_create` | Save a draft without sending |
+| `email_draft_list` | List all drafts |
+
+### Organization (7)
+
+| Tool | Description |
+|------|-------------|
+| `email_move` | Move an email to a different folder. Supports `sourceFolder` for IMAP/iCloud |
+| `email_delete` | Delete an email (trash or permanent). Supports `sourceFolder` for IMAP/iCloud |
+| `email_mark` | Mark as read/unread, starred, or flagged. Supports `sourceFolder` for IMAP/iCloud |
+| `email_label` | Add/remove labels (Gmail only) |
+| `email_folder_create` | Create a new folder |
+| `email_get_labels` | List all labels with counts (Gmail only) |
+| `email_get_categories` | List all categories (Outlook only) |
+
+### Batch Operations (3)
+
+| Tool | Description |
+|------|-------------|
+| `email_batch_delete` | Delete multiple emails at once (up to 1000 for Gmail, batches of 20 for Outlook, UID ranges for IMAP) |
+| `email_batch_move` | Move multiple emails to a folder in a single call |
+| `email_batch_mark` | Mark multiple emails read/unread, starred, or flagged at once |
+
+All batch tools accept a `sourceFolder` parameter for IMAP/iCloud and include a sequential fallback for maximum compatibility.
+
+## Usage with Claude Code
+
+Add the following to your `.mcp.json` file (project-level or global `~/.claude/.mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "email": {
+      "command": "npx",
+      "args": ["@marlinjai/email-mcp"]
+    }
+  }
+}
+```
+
+Once configured, you can ask Claude to interact with your email:
+
+- "Check my inbox for unread messages"
+- "Search for emails from alice@example.com in the last week"
+- "Reply to the latest email from Bob and thank him"
+- "Move all newsletters to the Archive folder"
+- "Delete all spam emails" (uses batch operations for speed)
+- "Draft a follow-up email to the team about the meeting"
+
+## Development
+
+```bash
+# Install dependencies
+pnpm install
+
+# Build the project
+pnpm build
+
+# Run in development mode (watch for changes)
+pnpm dev
+
+# Run tests
+pnpm test
+
+# Run tests in watch mode
+pnpm test:watch
+
+# Run integration tests (requires real email accounts)
+pnpm test:integration
+```
+
+## License
+
+MIT