MCP Email Server (HTTP Streaming)

This is a test service. To ensure security, enable authentication.

An HTTP streaming MCP (Model Context Protocol) server for sending emails via Gmail. Deployable to Cloud Foundry or any Node.js hosting platform.

Features

• HTTP streaming transport for remote MCP connections
• MCP tool: send_email for sending emails
• Support for To, CC, and BCC recipients
• HTML body support
• Cloud Foundry ready
• Health check endpoint

Prerequisites

• Node.js 22.x or higher
• Gmail account with App Password enabled
• Cloud Foundry CLI (for CF deployment)

Gmail Setup

To use this server, you need to generate a Gmail App Password:

1. Go to your Google Account settings
2. Navigate to Security → 2-Step Verification
3. Scroll down to "App passwords"
4. Generate a new app password for "Mail"
5. Save the 16-character password

Installation

npm install

Local Development

1. Set environment variables:

export GMAIL_USER=your-email@gmail.com
export GMAIL_PASSWORD=your-app-password
export PORT=3000

2. Start the server:

npm start

The server will start on port 3000 (or PORT environment variable).

Endpoints:

• Health check: http://localhost:3000/health
• MCP endpoint: http://localhost:3000/mcp

Cloud Foundry Deployment

1. Log in to Cloud Foundry:

cf login

2. Set environment variables:

cf set-env mcp-email-server GMAIL_USER your-email@gmail.com
cf set-env mcp-email-server GMAIL_PASSWORD your-app-password

3. Push the application:

cf push

4. Get your app URL:

cf app mcp-email-server

Your MCP server will be available at: https://your-app.cfapps.io/mcp

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "email": {
      "transport": "http",
      "url": "https://your-app.cfapps.io/mcp"
    }
  }
}

Claude Code CLI

Add to your MCP settings file (~/.claude/mcp_settings.json):

{
  "mcpServers": {
    "email": {
      "transport": "http",
      "url": "https://your-app.cfapps.io/mcp"
    }
  }
}

Custom MCP Client

Send POST requests to the MCP endpoint:

const response = await fetch('https://your-app.cfapps.io/mcp', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/list',
    params: {}
  })
});

MCP Tool Usage

send_email

Send an email via Gmail with HTML support.

Required Parameters:

• to (string): Recipient email address (comma-separated for multiple)
• subject (string): Email subject line
• body (string): Email body (HTML supported)

Optional Parameters:

• cc (string): CC recipients (comma-separated)
• bcc (string): BCC recipients (comma-separated)

Example Usage in Claude:

Send an email to john@example.com with subject "Meeting Tomorrow" and body "<h1>Reminder</h1><p>Don't forget our meeting at 2pm!</p>"

Claude will use the send_email tool to send the email through your deployed server.

API Endpoints

GET /health

Health check endpoint

Response:

{
  "status": "ok",
  "service": "mcp-email-server",
  "gmail_configured": true
}

POST /mcp

HTTP streaming endpoint for MCP protocol communication

This is the main endpoint that MCP clients connect to.

Request format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Tool Schema

{
  "name": "send_email",
  "description": "Send an email via Gmail. Supports HTML content in the body and optional CC/BCC recipients.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "to": {
        "type": "string",
        "description": "Recipient email address"
      },
      "subject": {
        "type": "string",
        "description": "Email subject line"
      },
      "body": {
        "type": "string",
        "description": "Email body content (HTML is supported)"
      },
      "cc": {
        "type": "string",
        "description": "CC recipients (comma-separated)"
      },
      "bcc": {
        "type": "string",
        "description": "BCC recipients (comma-separated)"
      }
    },
    "required": ["to", "subject", "body"]
  }
}

Testing

Test the health endpoint:

curl https://your-app.cfapps.io/health

Test listing tools:

curl -X POST https://your-app.cfapps.io/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Test sending an email:

curl -X POST https://your-app.cfapps.io/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "send_email",
      "arguments": {
        "to": "recipient@example.com",
        "subject": "Test Email",
        "body": "<h1>Hello</h1><p>This is a test email.</p>"
      }
    }
  }'

Security Notes

• Never commit your Gmail credentials to version control
• Use Gmail App Passwords, not your regular password
• Store credentials as environment variables in Cloud Foundry
• Consider adding authentication/authorization for production use
• Add rate limiting to prevent abuse
• Use HTTPS in production (automatic with Cloud Foundry)

Architecture

The server uses:

• Express - HTTP server
• @modelcontextprotocol/sdk - MCP protocol implementation
• nodemailer - Email sending functionality
• HTTP streaming - For MCP communication via POST requests

Troubleshooting

Authentication Errors

• Ensure 2-Step Verification is enabled on your Gmail account
• Generate a new App Password specifically for this application
• Verify environment variables: cf env mcp-email-server

Connection Issues

• Verify the app is running: cf app mcp-email-server
• Check logs: cf logs mcp-email-server --recent
• Test the health endpoint

Email Not Sending

• Check Cloud Foundry logs for errors
• Verify Gmail credentials are correct
• Ensure recipient addresses are valid

Monitoring

View logs:

cf logs mcp-email-server

View recent logs:

cf logs mcp-email-server --recent

Restart the app:

cf restart mcp-email-server

Scaling

Scale instances:

cf scale mcp-email-server -i 2

Scale memory:

cf scale mcp-email-server -m 512M