# 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

```bash
npm install
```

## Local Development

1. Set environment variables:
```bash
export GMAIL_USER=your-email@gmail.com
export GMAIL_PASSWORD=your-app-password
export PORT=3000
```

2. Start the server:
```bash
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:
```bash
cf login
```

2. Set environment variables:
```bash
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:
```bash
cf push
```

4. Get your app URL:
```bash
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`

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

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

### Custom MCP Client

Send POST requests to the MCP endpoint:
```javascript
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:
```json
{
  "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:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}
```

## Tool Schema

```json
{
  "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:
```bash
curl https://your-app.cfapps.io/health
```

Test listing tools:
```bash
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:
```bash
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:
```bash
cf logs mcp-email-server
```

View recent logs:
```bash
cf logs mcp-email-server --recent
```

Restart the app:
```bash
cf restart mcp-email-server
```

## Scaling

Scale instances:
```bash
cf scale mcp-email-server -i 2
```

Scale memory:
```bash
cf scale mcp-email-server -m 512M
```