# mcp-emailjs

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server for [EmailJS](https://www.emailjs.com) — lets AI agents like Claude send emails, validate configurations, and query email history directly through EmailJS.

## ⚠️ Required: enable non-browser API access

EmailJS blocks API calls from non-browser environments by default. Since this MCP
server runs as a server process (not a browser), you **must** enable API access or
`send_email` will fail with:

> `403: API access from non-browser environments is currently disabled.`

To enable it:

1. Go to [EmailJS Account → Security](https://dashboard.emailjs.com/admin/account/security)
2. Turn on **"Allow EmailJS API for non-browser applications"**
3. Save

> `get_email_history` works without this, but `send_email` and `validate_config` require it.

## Tools

| Tool | Description |
|---|---|
| `send_email` | Send an email using an EmailJS template with dynamic parameters |
| `validate_config` | Validate credentials and template ID before sending |
| `get_email_history` | Retrieve history of emails sent via your EmailJS account |

## Known limitations

**Templates cannot be created or edited programmatically.** EmailJS does not
expose a public API for template management — templates must be created and
edited through the [EmailJS dashboard](https://dashboard.emailjs.com). This MCP
can only *use* existing templates (by their `template_id`), not create them.

If you'd like EmailJS to add a template-management API, please 👍 and comment on
the feature request: [emailjs-sdk#70](https://github.com/emailjs-com/emailjs-sdk/issues/70).

## Installation

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "emailjs": {
      "command": "npx",
      "args": ["-y", "mcp-emailjs"],
      "env": {
        "EMAILJS_SERVICE_ID": "your_service_id",
        "EMAILJS_PUBLIC_KEY": "your_public_key",
        "EMAILJS_PRIVATE_KEY": "your_private_key"
      }
    }
  }
}
```

> **Config file location:**
> - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
> - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### Cursor / other MCP clients

```json
{
  "mcpServers": {
    "emailjs": {
      "command": "npx",
      "args": ["-y", "mcp-emailjs"],
      "env": {
        "EMAILJS_SERVICE_ID": "your_service_id",
        "EMAILJS_PUBLIC_KEY": "your_public_key",
        "EMAILJS_PRIVATE_KEY": "your_private_key"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `EMAILJS_SERVICE_ID` | Yes* | Your EmailJS service ID |
| `EMAILJS_PUBLIC_KEY` | Yes* | Your EmailJS public key |
| `EMAILJS_PRIVATE_KEY` | No | Your EmailJS private key (required for `get_email_history`) |

*Can be passed per tool call as parameters instead of env vars.

## Credential Priority

Credentials are resolved in this order:
1. **Parameter** passed in the tool call (overrides everything)
2. **Environment variable**
3. Error with a descriptive message

This allows using multiple EmailJS accounts in the same session.

## Usage Examples

### Send an email

```
Send an email using template "template_contact" with:
- to_name: "Alice"
- to_email: "alice@example.com"
- message: "Hello from Claude!"
```

### Validate your config

```
Validate my EmailJS configuration for service "service_gmail" and template "template_welcome"
```

### Check email history

```
Show me the last 10 emails I sent via EmailJS
```

## Where to find your credentials

1. Go to [EmailJS Dashboard](https://dashboard.emailjs.com)
2. **Service ID** → Email Services → your service
3. **Public Key** → Account → API Keys → Public Key
4. **Private Key** → Account → API Keys → Private Key

## Local Development

```bash
git clone https://github.com/ElizioMartins/mcp-emailjs
cd mcp-emailjs
npm install
npm run build

# Test with MCP Inspector
npm run inspector
```

## License

MIT