OpenSES MCP

Connect Claude, ChatGPT, Cursor and other AI assistants to OpenSES, 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 · Docs · Agent skill · npm

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:

{
  "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 bridge. For Claude Desktop you can instead install openses.mcpb from the 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).

{
  "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 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

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.

mcp-server

Documentation