Skip to main content
Glama
Cresca MCP Server

Cresca MCP Server

README.md
# Cresca MCP server

Send transactional email, check delivery, manage email templates and add contacts from your AI assistant.

This is a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for the [Cresca](https://www.cresca.xyz) email API. Connect it to Claude Code, Claude Desktop, Cursor or any other MCP client, and you can ask in plain words:

> Send a test of the password-reset template to me@acme.com with NAME set to Ana.

> Did the order confirmation we sent to sam@example.com an hour ago get delivered?

> Create a draft template called "trial-ending" with a subject and a short HTML body, then show it to me before publishing.

> Add these 40 beta testers to a contact list called "Beta".

The server runs on your own machine over stdio and calls Cresca's public REST API at `https://api.cresca.xyz/api/v1` with your API key. Your key stays in your local environment and is only ever sent to that API.

> **Sending is real.** `send_email` and `send_batch_emails` send real email to real people, and a sent email cannot be recalled (only a scheduled or still-queued one can be canceled). The tools tell the assistant to confirm the recipients and content with you first, and they are marked destructive so MCP clients ask before running them. Read what the assistant is about to send before you approve it.

## Contents

- [What you can do](#what-you-can-do)
- [Requirements](#requirements)
- [Install](#install)
- [Connect your MCP client](#connect-your-mcp-client)
- [Tools](#tools)
- [Limits](#limits)
- [Not supported](#not-supported)
- [Security](#security)
- [Troubleshooting](#troubleshooting)
- [Development](#development)

## What you can do

| Task | Tools |
| --- | --- |
| Send one email, or up to 100 different emails in one request | `send_email`, `send_batch_emails` |
| Check whether an email was delivered, bounced or is still queued | `get_email`, `list_emails` |
| Reschedule or cancel an email that has not gone out yet | `update_scheduled_email`, `cancel_email` |
| Draft, review, publish and delete email templates with `{{{VARIABLES}}}` | `create_template`, `get_template`, `list_templates`, `update_template`, `publish_template`, `delete_template` |
| Add people to a marketing contact list | `add_contacts` |

## Requirements

- Node.js 18 or newer
- A Cresca account with a verified sending domain and an active sender. The [quickstart](https://www.cresca.xyz/docs/quickstart) covers both.
- An API key from [app.cresca.xyz/api-keys](https://app.cresca.xyz/api-keys):
  - **Sending access** keys can only use `send_email` and `send_batch_emails`. Every other tool returns `401 restricted_api_key`.
  - **Full access** keys can use every tool.

New to Cresca? You can [start free for 30 days](https://app.cresca.xyz/signup), no credit card required.

## Install

There is nothing to install by hand. The server is published on npm as [`@crescadotxyz/mcp`](https://www.npmjs.com/package/@crescadotxyz/mcp), and the client configurations below start it with `npx -y @crescadotxyz/mcp`, which downloads it the first time and reuses it after that.

To run it from source instead:

```bash
git clone https://github.com/lalitkumarjangid/cresca-mcp.git
cd cresca-mcp
npm install
npm test        # optional: runs the test suite against a mocked API
```

Then replace `npx -y @crescadotxyz/mcp` in the snippets below with `node /absolute/path/to/cresca-mcp/src/index.js`.

A hosted (remote) version that needs no local install is planned.

## Connect your MCP client

| Variable | Required | Default | Meaning |
| --- | --- | --- | --- |
| `CRESCA_API_KEY` | yes | | Your API key (`cr_live_...`). Sent only as `Authorization: Bearer ...` and never logged. |
| `CRESCA_API_URL` | no | `https://api.cresca.xyz/api/v1` | Base URL including `/api/v1`. Must be `https` (plain `http` is allowed only for `localhost`). |

The server starts without a key, so your client can list the tools, but every tool call fails with a clear message until `CRESCA_API_KEY` is set.

In the snippets below, replace `cr_live_...` with your key.

### Claude Code

```bash
claude mcp add --transport stdio --env CRESCA_API_KEY=cr_live_... cresca \
  -- npx -y @crescadotxyz/mcp
```

Add `--scope user` to make it available in every project. Check it with `claude mcp list`, or `/mcp` inside a session.

### Claude Desktop

Open Settings, then Developer, then Edit Config. On macOS the file is `~/Library/Application Support/Claude/claude_desktop_config.json`. Add the server and restart Claude Desktop:

```json
{
  "mcpServers": {
    "cresca": {
      "command": "npx",
      "args": ["-y", "@crescadotxyz/mcp"],
      "env": {
        "CRESCA_API_KEY": "cr_live_..."
      }
    }
  }
}
```

If Claude Desktop cannot find `npx` (common with nvm), set `"command"` to the full path that `which npx` prints.

### Cursor

Add the same block to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project):

```json
{
  "mcpServers": {
    "cresca": {
      "command": "npx",
      "args": ["-y", "@crescadotxyz/mcp"],
      "env": {
        "CRESCA_API_KEY": "cr_live_..."
      }
    }
  }
}
```

### Other MCP clients

Any client that can start a stdio server works: the command is `npx -y @crescadotxyz/mcp` with `CRESCA_API_KEY` in its environment.

Keep your key out of any configuration file you commit to a repository.

## Tools

| Tool | Endpoint | What it does | Key |
| --- | --- | --- | --- |
| `send_email` | `POST /emails` | **Sends** one email to up to 50 recipients, with HTML/text or a published template, attachments, tags, headers, scheduling | sending or full |
| `send_batch_emails` | `POST /emails/batch` | **Sends** 1 to 100 different emails in one all-or-nothing request | sending or full |
| `get_email` | `GET /emails/:id` | Retrieves one email and its latest status (`last_event`) | full |
| `list_emails` | `GET /emails` | Lists API emails, newest first, with cursor pagination | full |
| `update_scheduled_email` | `PATCH /emails/:id` | Changes the send time of a scheduled email | full |
| `cancel_email` | `POST /emails/:id/cancel` | Cancels a scheduled or queued email | full |
| `create_template` | `POST /templates` | Creates a template draft | full |
| `list_templates` | `GET /templates` | Lists templates, newest first | full |
| `get_template` | `GET /templates/:id` | Retrieves a template by id or alias | full |
| `update_template` | `PATCH /templates/:id` | Changes a template draft (live email keeps the published version) | full |
| `publish_template` | `POST /templates/:id/publish` | Publishes the draft as the new live version | full |
| `delete_template` | `DELETE /templates/:id` | **Permanently** deletes a template | full |
| `add_contacts` | `POST /contacts` | Adds 1 to 1,000 contacts to a marketing list (creates the list if needed) | full |

Annotations: the four `get_`/`list_` tools are `readOnlyHint: true`. `send_email`, `send_batch_emails`, `cancel_email`, `update_template`, `publish_template` and `delete_template` are `destructiveHint: true`. Sending is additive in MCP terms, but it is irreversible and reaches real people, so it is marked destructive on purpose.

### Idempotency

`idempotency_key` is **required** on `send_email` and `send_batch_emails` (1 to 256 characters), and it's sent as the `Idempotency-Key` header. Build it from the real-world event the email is about, for example `order-confirmation/1042` or `password-reset/<reset request id>`, and reuse it on every retry. The server never generates one: a random key per call would let an assistant that calls the tool twice send two emails.

- Same key and body within 24 hours: the original result comes back (`idempotent_replayed: true`) and nothing is sent.
- Same key with a different body (usually rewritten content on a retry): the tool returns `already_sent: true` with a note that the task is complete. It is deliberately **not** an error, so the assistant doesn't re-plan and resend under a new key.
- Same key while the first request is still running (`409 concurrent_idempotent_requests`): retried with the same key.
- Keys last 24 hours. If work can resume after that (queues, long-running agents), keep your own record of what was sent.

### Errors and retries

API errors come back as tool errors in the form `Cresca API error <status> <name>: <message>`, for example `Cresca API error 403 invalid_from_address: ...`. A `429` also includes `Retry after N seconds.` See [www.cresca.xyz/docs/errors](https://www.cresca.xyz/docs/errors) for every name.

Only requests that are safe to repeat are retried (up to 2 times, on network errors, `429 rate_limit_exceeded`, `409 concurrent_idempotent_requests` and `5xx`): `GET` requests, and sends that carry their idempotency key. `monthly_quota_exceeded` is never retried. Other writes (cancel, publish, delete, create/update template, add contacts) are sent exactly once.

Inputs that the API would reject anyway (more than 50 recipients, html combined with a template, an empty batch, `after` and `before` together, and so on) are refused locally before any request is made.

## Limits

These follow the [Cresca API docs](https://www.cresca.xyz/docs/rate-limits), and the tool schemas enforce them:

| Limit | Value |
| --- | --- |
| Recipients per email (to + cc + bcc) | 50 |
| Emails per batch request | 100 (no attachments or `scheduled_at` in batches) |
| Attachments per email | 20, up to 7 MB in total, base64 only |
| Tags per email | 10, ASCII letters, numbers, `_` and `-`, up to 256 characters |
| Custom headers per email | 50 |
| Subject | 998 characters, single line |
| Scheduling | up to 30 days ahead; a past time sends immediately |
| Request body | 10 MB |
| Idempotency key | 1 to 256 characters, kept 24 hours |
| Template name / alias / preview text | 120 / 64 / 500 characters |
| Template variables | 50 per template; string values up to 2,000 characters |
| Contacts per request | 1,000; 120 requests per 15 minutes |
| List page size | 1 to 100, default 20 |
| Email retention | 30 days |

Requests per second depend on the plan (Free 2, Professional 10, Premium 20, Ultra 50, Enterprise 100) and are shared by all of an account's keys. API email uses the same monthly allowance as campaigns; each recipient counts as one email.

## Not supported

Cresca does not offer these, so there are no tools for them:

- Outbound webhooks (poll `get_email` / `list_emails` for status instead)
- SMTP relay
- Official SDKs (this server calls the REST API directly)
- Attachments by URL (`path`): send base64 `content`
- Open and click tracking for API email

The API is for transactional email (password resets, receipts, alerts). Newsletters and promotions belong in Cresca campaigns, which add the unsubscribe link marketing email needs.

## Security

- **Your key never leaves your machine except to the Cresca API.** It is read from the environment, sent only in the `Authorization` header to `CRESCA_API_URL`, never logged, and kept off the client object so it cannot appear if the object is printed.
- **No plain-text key transport.** The base URL must use `https`; plain `http` is accepted only for `localhost` during development.
- **Use the narrowest key.** If the assistant only needs to send, give it a Sending access key. It cannot read your email history or change templates.
- **Nothing is sent without you.** Send, cancel, publish and delete tools are marked destructive, so MCP clients ask for approval before running them.
- **Requests time out.** A request that gets no answer is abandoned after 30 seconds instead of hanging the tool call.
- **Never commit a key.** This repository's `.gitignore` excludes `.env` files and other secret files. If a key is ever exposed, delete it at [app.cresca.xyz/api-keys](https://app.cresca.xyz/api-keys) and create a new one.

Found a security problem? Email lalit@cresca.xyz rather than opening a public issue.

## Troubleshooting

| You see | What it means | Fix |
| --- | --- | --- |
| `CRESCA_API_KEY is not set` | The client started the server without the key | Add `CRESCA_API_KEY` to the server's `env` block and restart the client |
| `401 restricted_api_key` | A Sending access key was used for a tool that reads or changes data | Use a Full access key for that tool |
| `403 invalid_from_address` | The `from` address is not an active sender on a verified domain | Verify the domain and add the sender in [Sending Domains](https://app.cresca.xyz/sending-domains) |
| `422 validation_error` on a template send | The template is not published, or a required variable is missing | Publish the template, or pass every variable without a fallback |
| `429 rate_limit_exceeded` | Too many requests per second for your plan | The server retries safe requests; otherwise wait and try again |
| `429 monthly_quota_exceeded` | The plan's monthly email allowance is used up | Upgrade the plan or wait for the next period |
| The client cannot start the server | `npx` or `node` is not on the client's PATH | Use the full path to `npx` in `"command"` (`which npx` prints it) |

Every error name is listed at [www.cresca.xyz/docs/errors](https://www.cresca.xyz/docs/errors).

## Development

```
src/index.js    stdio entry point
src/server.js   MCP server: registers tools, formats results and errors
src/tools.js    one tool per endpoint: schemas, descriptions, annotations
src/client.js   HTTP client: auth header, idempotency, retries, errors
test/           node:test suites with a mocked fetch, plus a stdio smoke test
```

`npm test` never calls the real Cresca API: the tool tests use a mocked `fetch`, and the smoke test starts the server over stdio against a local mock HTTP server.

## License

MIT. See [LICENSE](LICENSE).

TDQS

A4.2/5.0

Scored across 13 tools

Disambiguation5/5

Each tool maps to a distinct resource+action pair, and the two send tools are clearly separated by semantics (one email to many recipients vs. many distinct emails in a batch), as are get_email vs. list_emails and update_scheduled_email vs. cancel_email. Template tools split cleanly along draft-vs-published lifecycle lines, so an agent can pick the right tool from the description alone.

Naming Consistency5/5

All names follow a single snake_case verb_noun convention (send_email, get_email, list_emails, create_template, publish_template, delete_template, add_contacts). The only variation is qualifying modifiers like batch and scheduled, which stay within the same pattern rather than introducing a new convention.

Tool Count5/5

Thirteen tools sit comfortably in the well-scoped range and each one covers a real operation: six email operations, six template lifecycle operations, and one contact import. There is no visible filler or redundant alias tool.

Completeness3/5

Email sending and the template lifecycle are covered end-to-end (send, batch, inspect, list, reschedule, cancel, draft, publish, delete), but the contacts surface is a single write-only add_contacts with no list/get/update/delete or suppression-list management, so an agent cannot verify or clean up contacts it imported. Suppression list handling is also only referenced implicitly, leaving notable dead ends outside the core send path.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues