Metadata-Version: 2.4
Name: coldsend-mcp-server
Version: 0.1.6
Summary: ColdSend MCP Server - AI-native email campaign management via Model Context Protocol
Author-email: ColdSend Team <dev@coldsend.io>
License: MIT
Project-URL: Homepage, https://coldsend.pro
Project-URL: Documentation, https://github.com/coldsend/coldsend-mcp-server#readme
Project-URL: Repository, https://github.com/coldsend/coldsend-mcp-server
Project-URL: Issues, https://github.com/coldsend/coldsend-mcp-server/issues
Keywords: mcp,email,campaigns,ai,coldsend,automation
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: FastAPI
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: fastapi>=0.109.0
Requires-Dist: uvicorn[standard]>=0.27.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: pydantic[email]>=2.5.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: email-validator>=2.1.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: authlib>=1.3.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=23.12.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.4.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
Requires-Dist: pytest-httpx>=0.25.0; extra == "test"
Dynamic: license-file

# ColdSend MCP Server

**AI-Native Email Campaign Management via Model Context Protocol**

ColdSend MCP Server enables AI assistants like Claude Desktop, Claude Code, Cursor IDE, Windsurf, OpenCode, and other MCP-compatible clients to manage cold email campaigns through natural language.

The server supports **dual transport** — Streamable HTTP (modern) and SSE (legacy) — for maximum client compatibility.

## Installation

```bash
pip install coldsend-mcp-server
```

## Quick Start

You only need your ColdSend API key to get started.

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "coldsend": {
      "command": "coldsend-mcp",
      "env": {
        "X-API-Key": "your-coldsend-api-key"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add coldsend https://mcp.coldsend.pro/mcp -t http -e X-API-Key=your-api-key
```

### Cursor IDE / Windsurf

1. Open Settings -> MCP
2. Add new MCP server:
   - Name: `ColdSend`
   - Type: `http` (Streamable HTTP)
   - URL: `https://mcp.coldsend.pro/mcp`
   - Headers: `X-API-Key: your-api-key`

### OpenCode

Add to your `opencode.jsonc`:

```jsonc
{
  "mcp": {
    "coldsend": {
      "type": "remote",
      "url": "https://mcp.coldsend.pro/sse",
      "enabled": true,
      "headers": {
        "X-API-Key": "{env:COLDSEND_API_KEY}"
      }
    }
  }
}
```

### Remote Server (No Installation Required)

You can connect directly to the hosted server without installing anything. Two transport endpoints are available:

| Transport | URL | Use With |
|-----------|-----|----------|
| Streamable HTTP | `https://mcp.coldsend.pro/mcp` | Claude Code, Cursor, VS Code, Smithery |
| SSE (legacy) | `https://mcp.coldsend.pro/sse` | OpenCode, older clients |

Header: `X-API-Key: your-api-key`

## Available Tools

### Campaign Management

| Tool | Description |
|------|-------------|
| `campaigns.create` | Create a new email campaign |
| `campaigns.list` | List all campaigns with filtering |
| `campaigns.get` | Get specific campaign details |
| `campaigns.update` | Update campaign configuration |
| `campaigns.pause` | Pause an active campaign |
| `campaigns.resume` | Resume a paused campaign |
| `campaigns.delete` | Delete a campaign permanently |

### Lead Management

| Tool | Description |
|------|-------------|
| `leads.upload` | Upload leads from CSV file |
| `leads.upload_progress` | Check CSV upload job progress |
| `leads.add_manual` | Add leads manually with custom data |
| `leads.list` | List leads in a campaign with filtering |
| `leads.get` | Get specific lead details |
| `leads.update` | Update lead data |
| `leads.delete` | Remove leads from campaign |
| `leads.export` | Export leads as CSV |

### Analytics

| Tool | Description |
|------|-------------|
| `analytics.campaign` | Campaign performance analytics |
| `analytics.timeline` | Timeline-based campaign analytics |

### Domain Management

| Tool | Description |
|------|-------------|
| `domains.list` | List all domains with status |
| `domains.get` | Get domain details with DNS records |
| `domains.add` | Add new domain for verification |
| `domains.progress` | Check domain activation progress |
| `domains.activate` | Activate domain after DNS setup |
| `domains.get_redirect` | Get domain redirect configuration |
| `domains.set_redirect` | Configure domain redirect rules |
| `domains.delete_redirect` | Remove domain redirect |
| `domains.delete` | Delete domain permanently |

### Sender Account Management

| Tool | Description |
|------|-------------|
| `sender.list` | List all sender inboxes |
| `sender.get` | Get sender account details |
| `sender.quotas` | Get inbox sending quotas |
| `sender.daily_usage` | Get daily usage statistics |
| `sender.create_coldsend` | Create ColdSend native inbox |
| `sender.create_smtp` | Create custom SMTP inbox (BYOC) |
| `sender.test` | Send test email |
| `sender.delete` | Delete inbox permanently |
| `sender.bulk_create_coldsend` | Bulk create ColdSend inboxes |
| `sender.bulk_create_smtp` | Bulk create SMTP inboxes |
| `sender.bulk_smtp_progress` | Check bulk SMTP creation progress |
| `sender.bulk_delete` | Bulk delete sender accounts |
| `sender.bulk_delete_progress` | Check bulk delete progress |

### Reply Management

| Tool | Description |
|------|-------------|
| `replies.list` | List reply conversations |
| `replies.thread` | Get reply thread details |
| `replies.messages` | Get messages in a thread |
| `replies.send` | Send reply to a thread |
| `replies.mark_read` | Mark thread as read |
| `replies.toggle_star` | Star/unstar a thread |

## Example Interactions

**Creating a Campaign:**

> Create a new campaign called "Q1 Outreach" starting January 15th with a daily limit of 100 emails.

**Checking Performance:**

> How is my Q1 Outreach campaign performing?

**Uploading Leads:**

> Upload these leads to my Q1 Outreach campaign: [paste CSV]

**Managing Domains:**

> Add the domain outreach.acme.com and show me the DNS records I need to configure.

**Inbox Health:**

> Check the health of all my sender inboxes and flag any issues.

**Managing Replies:**

> Show me all unread reply threads from my Q1 Outreach campaign.

**Sending Replies:**

> Reply to the thread from john@acme.com saying "Thanks for your interest, let's schedule a call."

**Bulk Inbox Creation:**

> Create 5 ColdSend inboxes on my domain example.com with prefixes sales1 through sales5.

## Authentication

The MCP server uses API key authentication. Pass your ColdSend API key via the `X-API-Key` header — the server forwards it securely to the ColdSend API.

Get your API key from your [ColdSend dashboard](https://cloud.coldsend.pro).

### Smithery

This server is also available on [Smithery](https://smithery.ai/servers/pipelinescientists/coldsend-mcp) if you prefer to use it from there.

## Transport Endpoints

The server exposes two transport protocols on different paths:

| Path | Transport | Description |
|------|-----------|-------------|
| `/mcp` | Streamable HTTP | Modern MCP transport (recommended) |
| `/sse` | SSE | Legacy transport for older clients |
| `/messages` | SSE POST | Message endpoint for SSE transport |
| `/health` | HTTP GET | Health check for Kubernetes probes |
| `/` | HTTP GET | Service info with transport discovery |

## Configuration

The server works out of the box with sensible defaults. All configuration is optional:

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `COLDSEND_API_URL` | `https://api.coldsend.pro/api/public/v1` | ColdSend API endpoint |
| `MCP_PORT` | `8080` | Server port |
| `LOG_LEVEL` | `INFO` | Logging level |

## Requirements

- Python 3.11+

## Links

- **Website**: [coldsend.pro](https://coldsend.pro)
- **API Docs**: [docs.coldsend.pro](https://docs.coldsend.pro)
- **Support**: support@coldsend.pro

## License

MIT License - see [LICENSE](LICENSE) for details.

---

**Built with [Model Context Protocol](https://modelcontextprotocol.io/) by the ColdSend Team**
