smtp-imap-mcp-lib

An MCP (Model Context Protocol) server that exposes SMTP and IMAP capabilities as tools. Works both as a stdio process (e.g. with Claude Desktop) and as an in-process library that you call directly from your own TypeScript/JavaScript code.

Author: @appler1009

Features

| Tool | Description | |---|---| | smtpSendEmail | Send an email via SMTP | | smtpTestConnection | Verify SMTP server reachability and credentials | | imapTestConnection | Verify IMAP server reachability and credentials | | imapListFolders | List all mailbox folders | | imapListMessages | List messages in a folder (most recent first) | | imapGetMessage | Fetch a single message by UID (headers + body) | | imapSearchMessages | Search messages by subject, sender, date range, or read status |

Installation

npm install smtp-imap-mcp-lib
# or
pnpm add smtp-imap-mcp-lib

Credential resolution

Every tool accepts credentials through one of three mechanisms, tried in this order:

1. Inline (direct parameters)

Pass host, username, and password directly in the tool input. port and secure are optional.

{
  "host": "smtp.gmail.com",
  "port": 587,
  "secure": false,
  "username": "[email protected]",
  "password": "app-password",
  "from": "[email protected]",
  "to": "[email protected]",
  "subject": "Hello"
}

2. Named config profile (configId)

Point to a profile in a JSON credentials file. Set the file path via:

• the SMTP_IMAP_CONFIG_FILE environment variable, or
• the configFilePath option in CredentialResolver.

credentials.json

{
  "work-smtp": {
    "host": "smtp.company.com",
    "port": 587,
    "secure": false,
    "username": "[email protected]",
    "password": "secret"
  },
  "work-imap": {
    "host": "imap.company.com",
    "port": 993,
    "secure": true,
    "username": "[email protected]",
    "password": "secret"
  }
}

Then pass "configId": "work-smtp" instead of inline credentials.

3. Environment variables

Set these and omit credentials from the tool input entirely:

# SMTP defaults
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_SECURE=false
[email protected]
SMTP_PASSWORD=your-password

# IMAP defaults
IMAP_HOST=imap.example.com
IMAP_PORT=993
IMAP_SECURE=true
[email protected]
IMAP_PASSWORD=your-password

Usage: stdio MCP server

As a global CLI

npx smtp-imap-mcp

Claude Desktop configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "smtp-imap": {
      "command": "npx",
      "args": ["smtp-imap-mcp"],
      "env": {
        "SMTP_IMAP_CONFIG_FILE": "/path/to/credentials.json"
      }
    }
  }
}

Or with inline env-var credentials:

{
  "mcpServers": {
    "smtp-imap": {
      "command": "npx",
      "args": ["smtp-imap-mcp"],
      "env": {
        "SMTP_HOST": "smtp.gmail.com",
        "SMTP_PORT": "587",
        "SMTP_SECURE": "false",
        "SMTP_USERNAME": "[email protected]",
        "SMTP_PASSWORD": "app-password",
        "IMAP_HOST": "imap.gmail.com",
        "IMAP_PORT": "993",
        "IMAP_SECURE": "true",
        "IMAP_USERNAME": "[email protected]",
        "IMAP_PASSWORD": "app-password"
      }
    }
  }
}

Usage: in-process library

Embed the MCP server in your own process

import { createMcpServer } from 'smtp-imap-mcp-lib';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';

const server = createMcpServer();
await server.connect(new StdioServerTransport());

Provide a custom CredentialResolver:

import { createMcpServer, CredentialResolver } from 'smtp-imap-mcp-lib';

const resolver = new CredentialResolver({
  config: {
    'my-smtp': { host: 'smtp.example.com', port: 587, secure: false, username: 'u', password: 'p' },
  },
});

const server = createMcpServer(resolver);

Call tool functions directly (no MCP protocol)

import { smtpSendEmail, imapListMessages, CredentialResolver } from 'smtp-imap-mcp-lib';

const resolver = new CredentialResolver({
  configFilePath: './credentials.json',
});

// Send an email
const result = await smtpSendEmail(resolver, {
  configId: 'work-smtp',
  from: '[email protected]',
  to: '[email protected]',
  subject: 'Meeting tomorrow',
  text: 'See you at 10am.',
});
console.log(JSON.parse(result.content[0].text));
// { messageId: '<...>', accepted: ['[email protected]'], rejected: [] }

// List messages
const msgs = await imapListMessages(resolver, {
  configId: 'work-imap',
  mailbox: 'INBOX',
  limit: 10,
});
console.log(JSON.parse(msgs.content[0].text));

All exported functions

// SMTP
import { smtpSendEmail, smtpTestConnection } from 'smtp-imap-mcp-lib';

// IMAP
import {
  imapTestConnection,
  imapListFolders,
  imapListMessages,
  imapGetMessage,
  imapSearchMessages,
} from 'smtp-imap-mcp-lib';

// Infrastructure
import { CredentialResolver, createMcpServer } from 'smtp-imap-mcp-lib';

Every function returns { content: [{ type: 'text', text: string }], isError?: boolean }. On success, text is a JSON string with the result. On error, isError is true and text contains the error message.

Tool reference

smtpSendEmail

| Field | Type | Required | Description | |---|---|---|---| | from | string | ✓ | Sender address | | to | string | string[] | ✓ | Recipient(s) | | subject | string | ✓ | Subject line | | text | string | | Plain-text body | | html | string | | HTML body | | cc | string | string[] | | CC recipients | | bcc | string | string[] | | BCC recipients | | replyTo | string | | Reply-To address | | + credential fields | | | See above |

imapListMessages

| Field | Type | Default | Description | |---|---|---|---| | mailbox | string | INBOX | Folder path | | limit | number | 50 | Max messages to return (most recent first) | | + credential fields | | | |

imapGetMessage

| Field | Type | Required | Description | |---|---|---|---| | uid | number | ✓ | UID of the message | | mailbox | string | INBOX | Folder path | | + credential fields | | | |

Returns: uid, subject, from[], to[], date, flags[], source (raw RFC 2822).

imapSearchMessages

| Field | Type | Description | |---|---|---| | subject | string | Substring match on subject | | from | string | Sender address or name | | to | string | Recipient address or name | | body | string | Body text search | | since | string | ISO 8601 date — messages on or after | | before | string | ISO 8601 date — messages before | | unseen | boolean | Only unread messages | | seen | boolean | Only read messages | | limit | number | Max UIDs to return (default 50) | | + credential fields | | |

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type-check without building
npm run typecheck

# Run the stdio server in development (no build needed)
npm run dev

License

MIT