MCP Server

Model Context Protocol integration

Enable AI assistants like Claude to interact with your email through a standardized protocol. The Mailpipe MCP server provides 20 tools for reading, sending, and managing email.

Quick Start

1

Get your API Key

Generate an API key from your Mailpipe dashboard. Navigate to Settings → API Keys and create a new key with the scopes you need.

Generate API Key
2

Configure Claude Desktop

Add the Mailpipe MCP server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

claude_desktop_config.json
{
  "mcpServers": {
    "mailpipe": {
      "command": "npx",
      "args": ["@mailpipe/mcp-server"],
      "env": {
        "MAILPIPE_API_KEY": "mp_live_your-api-key-here"
      }
    }
  }
}
3

Restart Claude Desktop

After saving the configuration file, restart Claude Desktop. You should see the Mailpipe tools available in your conversation. Try asking Claude to "check my inbox" or "list my unread emails".

Installation Options

NPX (Recommended)

Use npx to always run the latest version without installing globally.

npx @mailpipe/mcp-server

Global Install

Install globally for faster startup and offline usage.

npm install -g @mailpipe/mcp-server

Then use mailpipe-mcp as the command in your config.

Available Tools

The MCP server provides 20 tools organized by category. Each tool requires specific permission scopes.

Message Tools

10 tools
list_messages

List email messages with filters for mailbox, read status, starred status, and labels

mail:read
get_message

Get a single email message by ID including full content and attachments

mail:read
search_messages

Full-text search across all email messages with relevance scores

mail:read
archive_message

Archive an email message (removed from inbox but not deleted)

mail:write
delete_message

Permanently delete an email message

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

mail:write
apply_label

Apply a label to an email message

mail:write
remove_label

Remove a label from an email message

mail:write

Thread Tools

2 tools
get_thread

Get an email thread with all its messages

mail:read
summarize_inbox

Get inbox summary including unread count and recent messages

mail:read

Send Tools

3 tools
send_message

Send a new email message

mail:send
reply_to_message

Reply to an existing email message

mail:send
forward_message

Forward an email message to new recipients

mail:send

Draft Tools

1 tools
create_draft

Create a new email draft that can be edited before sending

mail:drafts

Mailbox Tools

1 tools
list_mailboxes

List all mailboxes connected to your organization

mailbox:read

Label Tools

2 tools
list_labels

List all email labels for organizing messages

labels:read
create_label

Create a new email label

labels:write

Permission Scopes

When creating an API key, select the scopes your AI assistant needs. Use the principle of least privilege - only grant the permissions required for your use case.

ScopeDescription
mail:readRead email messages and threads
mail:writeModify messages (archive, delete, star, labels)
mail:sendSend new emails and replies
mail:draftsCreate and manage drafts
mailbox:readList connected mailboxes
labels:readList labels
labels:writeCreate and modify labels

Programmatic Usage

For custom integrations, you can use the MCP server programmatically in your Node.js applications.

server.ts
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 (e.g., multi-tenant SaaS):

oauth-server.ts
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);
  },
});

MCP Resources

MCP resources provide read-only access to email data through URI patterns.

URIDescription
mailpipe://inboxInbox summary with unread count and recent messages
mailpipe://mailboxesList of all connected email accounts
mailpipe://labelsAll email labels for organization
mailpipe://messages/{id}A specific email message by ID
mailpipe://threads/{id}An email thread with all messages

NPM Package

@mailpipe/mcp-server

The MCP server is published as an npm package and can be installed in any Node.js project.

View on NPMView Source

Need Help?

Having trouble setting up the MCP server? Check our FAQ or reach out to support.

View FAQ

Found a Bug?

Report issues or request features on our GitHub repository.

Open an Issue