Metadata-Version: 2.4
Name: coldsend-mcp-server
Version: 0.1.2
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, Cursor IDE, Windsurf, and other MCP-compatible clients to manage cold email campaigns through natural language.

## 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"
      }
    }
  }
}
```

### Cursor IDE / Windsurf

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

### Remote Server (No Installation Required)

You can also connect directly to the hosted server without installing anything:

```
URL: https://mcp.coldsend.pro/mcp
Header: X-API-Key: your-api-key
```

## Available Tools

### Campaign Management

| Tool | Description |
|------|-------------|
| `create_campaign` | Create a new email campaign |
| `list_campaigns` | List all campaigns with filtering |
| `get_campaign` | Get specific campaign details |
| `update_campaign` | Update campaign configuration |
| `pause_campaign` | Pause an active campaign |
| `activate_campaign` | Activate/resume a campaign |
| `resume_campaign` | Resume a paused campaign |
| `delete_campaign` | Delete a campaign permanently |

### Lead Management

| Tool | Description |
|------|-------------|
| `upload_leads_csv` | Upload leads from CSV |
| `list_leads` | List leads in a campaign |
| `delete_lead` | Remove a lead |
| `get_lead_stats` | Get lead statistics |

### Analytics & Metrics

| Tool | Description |
|------|-------------|
| `get_campaign_analytics` | Comprehensive campaign analytics |
| `get_account_metrics` | Account-level metrics and quotas |
| `get_inbox_performance` | Inbox performance analysis |
| `compare_campaigns` | Compare multiple campaigns |

### Domain Management

| Tool | Description |
|------|-------------|
| `list_domains` | List all domains with verification status |
| `get_domain` | Get domain details with DNS records |
| `add_domain` | Add new domain for verification |
| `verify_domain_dns` | Trigger DNS verification check |
| `get_domain_activation_progress` | Check setup progress |
| `delete_domain` | Delete domain permanently |

### Sender Account Management

| Tool | Description |
|------|-------------|
| `list_sender_accounts` | List all sender inboxes |
| `create_coldsend_inbox` | Create ColdSend native inbox |
| `create_smtp_inbox` | Create custom SMTP inbox (BYOC) |
| `send_test_email` | Send test email to verify configuration |
| `pause_inbox` | Pause inbox temporarily |
| `resume_inbox` | Resume paused inbox |
| `delete_inbox` | Delete inbox permanently |
| `get_inbox_health` | Get detailed health report |

## 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.

## 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.

## 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**
