# sendscape-mcp

A local [MCP](https://modelcontextprotocol.io) server for [Sendscape](https://sendscape.ai). It lets Claude Code, Claude Desktop, Cursor and other MCP clients send email, and **attach files and inline images straight from your computer**.

The hosted Sendscape MCP server (`https://api.sendscape.ai/mcp`) runs on our side and cannot read your disk. This package runs on your machine, reads the files your assistant names and sends them through the public API. Nothing is stored on Sendscape.

## Install

You need Node.js 20+ and an API key from the Sendscape dashboard (API Keys).

**Claude Code**

```sh
claude mcp add sendscape \
  -e SENDSCAPE_API_KEY=ss_xxxxxxxxx \
  -e SENDSCAPE_FROM="Acme <hello@acme.com>" \
  -- npx -y sendscape-mcp
```

**Claude Desktop / Cursor** (`claude_desktop_config.json` / `.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "sendscape": {
      "command": "npx",
      "args": ["-y", "sendscape-mcp"],
      "env": {
        "SENDSCAPE_API_KEY": "ss_xxxxxxxxx",
        "SENDSCAPE_FROM": "Acme <hello@acme.com>"
      }
    }
  }
}
```

## Configuration

| Variable | Required | Description |
|---|---|---|
| `SENDSCAPE_API_KEY` | yes | API key (`ss_...`). Sending-only keys can send; `get_email` / `list_emails` need full access. |
| `SENDSCAPE_FROM` | no | Default from address. |
| `SENDSCAPE_REPLY_TO` | no | Default reply-to. |
| `SENDSCAPE_ALLOWED_DIRS` | no | Comma-separated folders attachments may be read from. Unset = any file the user can read. |
| `SENDSCAPE_API_URL` | no | Defaults to `https://api.sendscape.ai`. |

## Tools

| Tool | API |
|---|---|
| `send_email` | `POST /v1/emails`, with attachments from `localPath`, `url` (https) or base64 `content` |
| `send_batch_emails` | `POST /v1/emails/batch` (up to 100, no attachments) |
| `get_email` | `GET /v1/emails/{id}` |
| `list_emails` | `GET /v1/emails` |
| `send_event` | `POST /v1/events/send` |

### Attachments

```json
{
  "to": "ali@example.com",
  "subject": "Your invoice",
  "html": "<img src=\"cid:logo\"><p>Invoice attached.</p>",
  "attachments": [
    { "localPath": "/Users/me/Desktop/invoice.pdf" },
    { "localPath": "/Users/me/Pictures/logo.png", "content_id": "logo" }
  ]
}
```

- Exactly one of `localPath`, `url`, `content` per attachment.
- `content_id` makes an inline image: `<img src="cid:ID">`.
- Max 10 files, 10 MiB total; executables and scripts are refused. The server checks this before sending.
- File contents are never returned to the model, only the name and size.
- Every send carries an `Idempotency-Key`.

To test without emailing anyone, send to `delivered@sandbox.sendscape.ai`.

## Development

```sh
npm install
npm test
npm run build
SENDSCAPE_API_KEY=ss_... node dist/index.js
```

Release: bump `version` in `package.json` **and** `VERSION` in `src/client.ts`, then `npm publish`.