@mailpipe/mcp-server

MCP (Model Context Protocol) server for Mailpipe email management. This package enables AI assistants like Claude to interact with your email through a standardized protocol.

Installation

npm install @mailpipe/mcp-server

Configuration

Environment Variable

Set your Mailpipe API key as an environment variable:

export MAILPIPE_API_KEY=your-api-key-here

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mailpipe": {
      "command": "npx",
      "args": ["@mailpipe/mcp-server"],
      "env": {
        "MAILPIPE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Alternatively, if installed globally:

{
  "mcpServers": {
    "mailpipe": {
      "command": "mailpipe-mcp",
      "env": {
        "MAILPIPE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Programmatic Usage

import { MailpipeMCPServer } from '@mailpipe/mcp-server';

// Create server with API key authentication
const server = new MailpipeMCPServer({
  apiKey: process.env.MAILPIPE_API_KEY,
});

// Start with stdio transport (default for CLI usage)
await server.start('stdio');

// Or use HTTP transport for web integrations
await server.start('http', { port: 3000 });

// Or use SSE transport for real-time updates
await server.start('sse', { port: 3001 });

OAuth Authentication

For applications requiring OAuth:

const server = new MailpipeMCPServer({
  oauthToken: 'oauth-access-token',
  refreshToken: 'oauth-refresh-token',
  expiresAt: Date.now() + 3600000, // 1 hour
  scopes: ['mail:read', 'mail:write', 'mail:send'],
  onTokenRefresh: async (newTokens) => {
    // Persist refreshed tokens
    await saveTokens(newTokens);
  },
});

Available Tools

The MCP server provides 20 tools organized by category:

Message Tools (10 tools)

| Tool | Description | Required Scope | |------|-------------|----------------| | list_messages | List email messages with optional filters for mailbox, read status, starred status, and labels. Returns paginated results. | mail:read | | get_message | Get a single email message by ID including full content, attachments, and metadata. | mail:read | | search_messages | Full-text search across all email messages. Returns messages with relevance scores and highlighted matches. | mail:read | | archive_message | Archive an email message. Archived messages are removed from inbox but not deleted. | mail:write | | delete_message | Permanently delete an email message. This action cannot be undone. | mail:write | | mark_as_read | Mark an email message as read. | mail:write | | mark_as_unread | Mark an email message as unread. | mail:write | | star_message | Star or unstar an email message for easy access later. | mail:write | | apply_label | Apply a label to an email message for organization. | mail:write | | remove_label | Remove a label from an email message. | mail:write |

Thread Tools (2 tools)

| Tool | Description | Required Scope | |------|-------------|----------------| | get_thread | Get an email thread with all its messages. A thread groups related emails together (replies, forwards). | mail:read | | summarize_inbox | Get a summary of the inbox including unread count, recent messages, and top senders. Useful for getting an overview. | mail:read |

Send Tools (3 tools)

| Tool | Description | Required Scope | |------|-------------|----------------| | send_message | Send a new email message. Requires specifying recipients, subject, and body content. | mail:send | | reply_to_message | Reply to an existing email message. The reply will be added to the same thread. | mail:send | | forward_message | Forward an email message to new recipients. Optionally add a comment. | mail:send |

Draft Tools (1 tool)

| Tool | Description | Required Scope | |------|-------------|----------------| | create_draft | Create a new email draft. Drafts can be saved and edited before sending. | mail:drafts |

Mailbox Tools (1 tool)

| Tool | Description | Required Scope | |------|-------------|----------------| | list_mailboxes | List all mailboxes (email accounts) connected to this organization. Returns email addresses, providers, and unread counts. | mailbox:read |

Label Tools (2 tools)

| Tool | Description | Required Scope | |------|-------------|----------------| | list_labels | List all email labels for organizing messages. Returns label names, colors, and message counts. | labels:read | | create_label | Create a new email label for organizing messages. | labels:write |

Utility Tools (1 tool)

| Tool | Description | Required Scope | |------|-------------|----------------| | get_unread_count | Get the count of unread messages, optionally filtered by mailbox. Returns total unread and breakdown by mailbox/label. | mail:read |

Resources

MCP resources provide read-only access to email data:

Static Resources

| URI | Name | Description | |-----|------|-------------| | mailpipe://inbox | Inbox Summary | Current inbox summary including unread count, recent messages, and top senders | | mailpipe://mailboxes | Mailboxes | List of all connected mailboxes (email accounts) | | mailpipe://labels | Labels | List of all email labels for organization | | mailpipe://unread | Unread Count | Total unread message count across all mailboxes |

Resource Templates

| URI Template | Name | Description | |--------------|------|-------------| | mailpipe://messages/{id} | Email Message | A specific email message by ID | | mailpipe://threads/{id} | Email Thread | A specific email thread with all messages |

Prompts

Pre-built prompts for common email tasks:

| Prompt | Description | Arguments | |--------|-------------|-----------| | triage_inbox | Help triage unread emails by analyzing urgency, suggesting actions, and recommending organization strategies | mailboxId (optional) | | draft_reply | Draft a reply to an email with a specified tone (professional, friendly, formal, casual) | messageId (required), tone (optional) | | compose_email | Compose a new email with guidance on subject, body, and tone | purpose (required), recipient (optional), tone (optional) | | summarize_thread | Summarize an email thread including key points, decisions, and action items | threadId (required) | | find_emails | Help find emails matching a natural language description by suggesting search strategies | description (required) |

Transport Support

The MCP server supports multiple transport protocols:

Stdio (Default)

Standard input/output transport for CLI usage and Claude Desktop integration.

await server.start('stdio');

HTTP (JSON-RPC 2.0)

HTTP transport using JSON-RPC 2.0 protocol for web integrations.

await server.start('http', {
  port: 3000,
  corsOrigin: '*',
});

// Handle requests in your framework (e.g., Next.js)
const response = await server.handleHTTPRequest(request, {
  scopes: ['mail:read', 'mail:write'],
  clientId: 'client-123',
  userId: 'user-456',
});

SSE (Server-Sent Events)

SSE transport for real-time updates and streaming responses.

await server.start('sse', {
  heartbeatInterval: 30000,
  maxConnections: 100,
});

// Create a new SSE connection
const connection = server.createSSEConnection({
  scopes: ['mail:read'],
  clientId: 'client-123',
});

// Subscribe to resource updates
connection.subscribeToResource('mailpipe://inbox');

API Reference

MailpipeMCPServer

class MailpipeMCPServer {
  constructor(config: MCPServerConfig);

  // Start the server with specified transport
  start(transport: 'stdio'): Promise<void>;
  start(transport: 'http', options?: HTTPTransportOptions): Promise<void>;
  start(transport: 'sse', options?: SSETransportOptions): Promise<void>;

  // Stop the server
  stop(): Promise<void>;

  // HTTP request handling
  handleHTTPRequest(request: JSONRPCRequest, authContext?: AuthContext): Promise<JSONRPCResponse>;

  // SSE connection management
  createSSEConnection(authContext?: AuthContext, options?: SSETransportConfig): SSETransport;
  closeSSEConnection(connectionId: string): void;
  getSSEConnection(connectionId: string): SSETransport | undefined;
  getSSEConnections(): Map<string, SSETransport>;

  // Introspection
  getRegisteredTools(): ToolDefinition[];
  getRegisteredResources(): ResourceDefinition[];
  getRegisteredResourceTemplates(): ResourceTemplateDefinition[];
  getRegisteredPrompts(): PromptDefinition[];
  getCurrentTransport(): TransportType | null;
  getIsStarted(): boolean;
}

MCPServerConfig

interface MCPServerConfig {
  // API key authentication
  apiKey?: string;

  // OAuth authentication
  oauthToken?: string;
  refreshToken?: string;
  expiresAt?: number;
  scopes?: MCPScope[];
  onTokenRefresh?: (tokens: RefreshedTokens) => Promise<void>;

  // Optional custom API base URL
  baseUrl?: string;
}

Scopes

Available permission scopes:

| Scope | Description | |-------|-------------| | mail:read | Read email messages and threads | | mail:write | Modify messages (archive, delete, star, labels) | | mail:send | Send new emails and replies | | mail:drafts | Create and manage drafts | | mailbox:read | List connected mailboxes | | labels:read | List labels | | labels:write | Create and modify labels |

Requirements

• Node.js >= 18.0.0
• Mailpipe API key or OAuth credentials

License

MIT