MCP-email

This MCP server exposes a Gmail integration to Claude Desktop and other MCP clients, enabling you to read, search, send, reply, forward, manage drafts, labels, and attachments through a standardized interface. It is designed to resemble Gmail behavior, including quoting original messages, handling reply-to-all scenarios, and supporting time zone-aware date handling. You can run the server via NPX or install it locally and link it forClaude to load as an MCP server.

To use the server with Claude Desktop, add the MCP server configuration in Claude's Developer Mode, pointing to the NPX command variant of the package. Once loaded, Claude can invoke tools for reading emails, composing new messages, searching by filters, and managing labels and drafts. You can customize behavior using environment variables such as TIME_ZONE to ensure dates reflect the user’s locale and DEFAULT_ATTACHMENTS_FOLDER to specify where attachments are saved. The server also provides support for saving attachments to disk and for interacting with Gmail categories and labels through the provided tool set.

Prerequisites:

• Node.js (recommended) and npm installed on your system
• Basic familiarity with running commands in a terminal

Option A: Run with NPX (no local install, recommended)

1. Ensure you have Node.js and npm installed.
2. Run the MCP server directly:

npx @cristip73/email-mcp

3. First-time authentication (OAuth) with Gmail:

npx @cristip73/email-mcp auth

Option B: Clone and install locally

1. Clone the repository and install dependencies:

git clone https://github.com/cristip73/MCP-email-server.git
cd MCP-email-server
npm install

2. Build the server (if required by the project workflow):

npm run build

3. Authenticate with Gmail to grant access:

npm run auth

4. Make the package available to Claude (local development):

npm link

Note: If you plan to use NPX, you can skip local installation steps and rely on the package registry.

Environment variables and configuration:

• TIME_ZONE: Timezone in GMT format (e.g., GMT+2, GMT-5). Default is GMT+0 if not set.
• DEFAULT_ATTACHMENTS_FOLDER: Path where attachments will be saved. Ensure the directory exists and is writable.
• The server supports saving attachments from emails to a local folder and handling Gmail categories/labels through its tools.

Common issues:

• Ensure Gmail API OAuth credentials are correctly configured and the credentials file is accessible at runtime as described in the setup steps.
• When running via Claude, ensure the path to the built server (or the NPX invocation) matches the environment where Claude is configured to load the MCP server.
• If attachments fail to save, verify that the DEFAULT_ATTACHMENTS_FOLDER path is valid and has write permissions.

Configuration tips:

• You can set TIME_ZONE to reflect the user’s locale for accurate date/time rendering.
• Use npm link or a local build to make the server available to Claude during development.