npm package: @mailpipe/mcp-server
Description: MCP Server for Mailpipe email management
Latest version: 0.3.0

# @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

```bash
npm install @mailpipe/mcp-server
```

## Configuration

### Environment Variable

Set your Mailpipe API key as an environment variable:

```bash
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`

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

Alternatively, if installed globally:

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

## Programmatic Usage

```typescript
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:

```typescript
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.

```typescript
await server.start('stdio');
```

### HTTP (JSON-RPC 2.0)

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

```typescript
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.

```typescript
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

```typescript
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

```typescript
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