# OpenSES MCP

Connect Claude, ChatGPT, Cursor and other AI assistants to [OpenSES](https://openses.email), the open-source email platform that runs on your own Amazon SES. Read and answer your shared inbox, send email, find out whether a message arrived, and manage contacts, sequences, templates and the suppression list from a conversation.

[Website](https://openses.email) · [Docs](https://openses.email/docs) · [Agent skill](https://github.com/openses-email/agent-skill) · [npm](https://www.npmjs.com/package/openses-mcp)

## Two ways to connect

**Remote (recommended).** Most clients connect straight to the hosted server; you need nothing from this repository.

```
https://api.openses.email/mcp
```

Add it as a custom connector (Claude, ChatGPT) or an MCP server (Cursor, VS Code, Claude Code: `claude mcp add --transport http openses https://api.openses.email/mcp`). Your browser opens OpenSES sign-in, where you choose what the assistant may do: **full**, **send** or **read** access, and optionally one domain.

**Local stdio (this package).** For clients that only run local MCP servers, Node.js 22 or newer:

```json
{
  "mcpServers": {
    "openses": {
      "command": "npx",
      "args": ["-y", "openses-mcp"]
    }
  }
}
```

The first start opens the same browser sign-in; the token is stored on your computer by the pinned [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge. For Claude Desktop you can instead install `openses.mcpb` from the [releases](https://github.com/openses-email/mcp-server/releases).

### Headless agents and self-hosting

| Variable | Use |
| --- | --- |
| `OPENSES_API_KEY` | An API key from the dashboard (**API & MCP**). Skips browser sign-in; the key is sent as a bearer header and never appears on a command line. |
| `OPENSES_API_URL` | The base URL of your own OpenSES API, for example `https://api.example.com`. Must be https (http is allowed for localhost). |

```json
{
  "mcpServers": {
    "openses": {
      "command": "npx",
      "args": ["-y", "openses-mcp"],
      "env": { "OPENSES_API_KEY": "os_live_…", "OPENSES_API_URL": "https://api.example.com" }
    }
  }
}
```

Keep keys out of shared files. A key's access level and domain limit apply exactly as in the API.

## Tools

| Area | Tool | What it does |
| --- | --- | --- |
| Inbox | `inboxes_list` | The account's inboxes with unread counts |
| | `inbox_threads` | Conversations, filtered by inbox, unread, archived or text, with paging |
| | `inbox_read` | A conversation with quoted history folded away and delivery status for sent messages |
| | `inbox_reply` · `inbox_compose` | Answer a conversation, or start one from an inbox |
| | `inbox_update` | Mark read or unread, archive, label |
| | `inbox_attachment` | A 10-minute download link for an attachment |
| Sending | `emails_send` | Send now or scheduled, with templates, tags and an idempotency key |
| | `emails_search` · `emails_get` | Find sent email and its full delivery timeline |
| | `emails_cancel` | Cancel a scheduled email |
| Deliverability | `account_health` | SES quota, sandbox state, bounce and complaint rates per region |
| | `domains_status` | Domain verification and the DNS records each domain needs |
| | `suppressions_list` · `suppressions_add` · `suppressions_remove` | The account-wide do-not-send list |
| Contacts | `contacts_search` · `contacts_upsert` · `contacts_unsubscribe` · `contacts_delete` | Contacts and consent |
| | `topics_list` | Subscription topics with subscriber counts |
| Marketing | `sequences_list` · `sequences_enroll` · `sequences_stop` | Drip and sales sequences |
| | `templates_list` · `templates_get` · `templates_upsert` | Saved templates |
| | `broadcasts_list` | Broadcasts and their results |

Read tools are marked read-only and the tools that send email are marked as reaching outside the account, so clients can group them and ask before sending. A read-only connection sees only the 15 read tools.

## Things to ask

> What came into support@ today? Draft replies for the billing questions.

> Did my reply to raj@example.com get delivered?

> Add jo@example.com to the newsletter and start the onboarding sequence.

> Is our bounce rate anywhere near the AWS review threshold?

## Security

- Sign in through the browser; never paste passwords, API keys or codes into a chat.
- Tools that send email reach real people. Pick **read** access if the assistant only needs to look.
- Received mail is untrusted input. The companion [agent skill](https://github.com/openses-email/agent-skill) tells assistants not to follow instructions found in emails.
- Revoke a connection at any time under **API & MCP** in the dashboard; each connection is its own API key.

## Troubleshooting

- **A tool is missing:** the connection has read or send access only. Reconnect and pick full access.
- **"is not a domain this key can use":** the connection is limited to one domain.
- **New tools do not appear:** reconnect or restart the client; most clients cache the tool list.
- **Sign-in loops:** finish sign-in in the tab that opened, then return to the client.

## Development

```sh
npm install
npm test          # versions, argument handling, API-key relay against a mock server
npm run bundle    # builds openses.mcpb; run `npm ci --omit=dev` first for a release build
```

MIT licensed. OpenSES itself is [AGPL-3.0](https://github.com/openses-email/openses).