# Sidemail Model Context Protocol (MCP) Server

Sidemail MCP Server provides Model Context Protocol (MCP) integration for [Sidemail.io](https://sidemail.io/), enabling programmatic access to Sidemail's transactional email, contacts, domains, and Messenger features via MCP agent mode in VS Code and other MCP clients.

## Features

- Manage sending domains
- Test sending transactional emails
- Manage contacts and groups
- Create, update, and delete Messenger drafts
- Query sent emails and contacts

## Prerequisites

- Node.js v18 or newer
- Sidemail API Key

## Microsoft VS Code setup (assisted)

1. Open the Command Palette (`Ctrl/Cmd + Shift + P`).
2. Type **“MCP: Add Server…”** and select it.
3. Select **"NPM Package"**.
4. Enter `@sidemail/mcp` and confirm it.
5. Confirm the installation.
6. Enter your Sidemail API key and confirm it.

## Microsoft VS Code setup (manual)

Alternatively, you can install it manually by modifying the `mcp.json` configuration file.

1. Open the Command Palette (`Ctrl/Cmd + Shift + P`).
2. Type **“MCP: Open User Configuration”** and select it.
3. Add the configuration below and save changes.

```jsonc
{
	"servers": {
		"sidemail-mcp": {
			"type": "stdio",
			"command": "npx",
			"args": ["-y", "@sidemail/mcp"],
			"env": {
				"SIDEMAIL_API_KEY": "${input:sidemail-key}",
			},
		},
	},
	"inputs": [
		{
			"type": "promptString",
			"id": "sidemail-key",
			"description": "Sidemail API Key",
			"password": true,
		},
	],
}
```

## Claude Desktop setup

Edit (or create) the config file:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

```json
{
	"mcpServers": {
		"sidemail": {
			"command": "npx",
			"args": ["-y", "@sidemail/mcp"],
			"env": { "SIDEMAIL_API_KEY": "your-key" }
		}
	}
}
```

## Cursor setup

Create or edit `~/.cursor/mcp.json`:

```json
{
	"mcpServers": {
		"sidemail": {
			"command": "npx",
			"args": ["-y", "@sidemail/mcp"],
			"env": { "SIDEMAIL_API_KEY": "your-key" }
		}
	}
}
```

## CLI Usage

```sh
npx @sidemail/mcp
```

## MCP Server Tools

### Domains

- **list-domains**: List all sending domains
- **create-domain**: Add a new sending domain
- **delete-domain**: Remove a sending domain

### Messenger

- **list-messenger-drafts**: List Messenger drafts
- **get-messenger-draft**: Get Messenger draft by ID
- **create-messenger-draft**: Create a Messenger draft
- **update-messenger-draft**: Update a Messenger draft
- **delete-messenger-draft**: Delete a Messenger draft

### Groups

- **list-groups**: List all contact groups
- **create-group**: Create a new contact group
- **update-group**: Update a contact group

### Contacts

- **create-or-update-contact**: Create or update a contact
- **query-contacts**: Query contacts with filters
- **find-contact**: Find a contact by email
- **delete-contact**: Delete a contact

### Emails

- **send-email**: Send a transactional email (testing only)
- **query-emails**: Query sent emails