smartlead-mcp-by-leadmagic/INSTALLATION.md

💜 The Premier Model Context Protocol Server for SmartLead's Cold Email Automation Platform - Complete API coverage with 116+ tools for campaign management, lead tracking, smart delivery, and analytics. Beautiful purple-gradient installer, zero-config set

# 🚀 SmartLead MCP Server - Installation Guide

## 📦 Package Export Ready

Your SmartLead MCP Server is now fully built and packaged with **116+ API tools** covering the complete SmartLead API!

### 🎯 Package Details
- **Package Name**: `smartlead-mcp-by-leadmagic`
- **Version**: 1.6.1
- **Size**: 167.4 kB (1.0 MB unpacked)
- **Files**: 134 files including all tools and documentation
- **Tools**: 116+ SmartLead API endpoints

---

## 🔥 Installation Options

### Option 1: NPX (Recommended - No Installation Required)
```bash
# Interactive installer with beautiful UI
npx smartlead-mcp-by-leadmagic install

# Direct usage with API key
SMARTLEAD_API_KEY=your-key npx smartlead-mcp-by-leadmagic

# With all tools enabled
SMARTLEAD_API_KEY=your-key SMARTLEAD_ADVANCED_TOOLS=true SMARTLEAD_ADMIN_TOOLS=true npx smartlead-mcp-by-leadmagic
```

### Option 2: Global Installation
```bash
# Install globally
npm install -g smartlead-mcp-by-leadmagic

# Run anywhere
smartlead-mcp-by-leadmagic install
```

### Option 3: Local Installation from Package
```bash
# Install from the exported package
npm install ./smartlead-mcp-by-leadmagic-1.6.1.tgz

# Or from npm registry
npm install smartlead-mcp-by-leadmagic
```

---

## 🛠️ MCP Client Setup

### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "smartlead": {
      "command": "npx",
      "args": ["smartlead-mcp-by-leadmagic"],
      "env": {
        "SMARTLEAD_API_KEY": "your-api-key-here",
        "SMARTLEAD_ADVANCED_TOOLS": "true",
        "SMARTLEAD_ADMIN_TOOLS": "true"
      }
    }
  }
}
```

### Cursor (with Cline)
Add to VS Code `settings.json`:
```json
{
  "cline.mcpServers": {
    "smartlead": {
      "command": "npx",
      "args": ["smartlead-mcp-by-leadmagic"],
      "env": {
        "SMARTLEAD_API_KEY": "your-api-key-here",
        "SMARTLEAD_ADVANCED_TOOLS": "true",
        "SMARTLEAD_ADMIN_TOOLS": "true"
      }
    }
  }
}
```

### Windsurf
Add to Windsurf configuration:
```json
{
  "mcpServers": {
    "smartlead": {
      "command": "npx",
      "args": ["smartlead-mcp-by-leadmagic"],
      "env": {
        "SMARTLEAD_API_KEY": "your-api-key-here",
        "SMARTLEAD_ADVANCED_TOOLS": "true",
        "SMARTLEAD_ADMIN_TOOLS": "true"
      }
    }
  }
}
```

---

## 🎯 Tool Loading Configuration

### Essential Tools (Always Loaded - 49 Tools)
- **Campaign Management** (14 tools)
- **Lead Management** (17 tools)  
- **Email Account Management** (10 tools)
- **Basic Statistics** (8 tools)

### Advanced Tools (Optional - 50+ Tools)
Set `SMARTLEAD_ADVANCED_TOOLS=true` to enable:
- **Smart Delivery** (25 tools)
- **Global Analytics** (20 tools)
- **Webhooks** (5 tools)

### Administrative Tools (Optional - 11+ Tools)
Set `SMARTLEAD_ADMIN_TOOLS=true` to enable:
- **Client Management** (6 tools)
- **Smart Senders** (5 tools)

---

## 🔑 API Key Setup

1. Visit [SmartLead Dashboard](https://app.smartlead.ai)
2. Navigate to Settings → API Keys
3. Generate your API key
4. Use in environment variable: `SMARTLEAD_API_KEY=your-key`

---

## ✅ Verification

Test your installation:
```bash
# Test with interactive installer
npx smartlead-mcp-by-leadmagic install

# Test direct connection
SMARTLEAD_API_KEY=your-key npx smartlead-mcp-by-leadmagic
```

---

## 📊 Complete API Coverage

This package includes **ALL** SmartLead API endpoints:

### 📧 Campaign Management (14 tools)
- Create, update, delete campaigns
- Manage sequences and schedules
- Campaign analytics and reporting

### 👥 Lead Management (17 tools)  
- Import, export, and manage leads
- Lead categories and segmentation
- Conversation history and replies

### 📊 Analytics & Reporting (20 tools)
- Campaign performance metrics
- Lead statistics and insights
- Mailbox health monitoring

### 📧 Email Account Management (16 tools)
- Add/remove email accounts
- Warmup configuration
- Account health monitoring

### 🎯 Smart Delivery (25 tools)
- Spam testing and placement
- Deliverability optimization
- IP and domain monitoring

### 🔗 Webhooks (5 tools)
- Event-driven integrations
- Real-time notifications
- Webhook management

### 👥 Client Management (6 tools)
- White-label operations
- Multi-client support
- API key management

### 🌐 Smart Senders (5 tools)
- Domain purchasing
- Mailbox generation
- Vendor management

---

## 🎨 Features

- ✅ **116+ API Tools** - Complete SmartLead API coverage
- ✅ **Beautiful Interactive Installer** - Purple gradient UI
- ✅ **Zero Configuration** - Works out of the box
- ✅ **Type Safety** - Full TypeScript implementation
- ✅ **Error Handling** - Comprehensive error messages
- ✅ **MCP Compliant** - Works with all MCP clients
- ✅ **Production Ready** - Enterprise-grade reliability

---

## 🆘 Support

- **Documentation**: [GitHub Repository](https://github.com/LeadMagic/smartlead-mcp-server)
- **Issues**: [GitHub Issues](https://github.com/LeadMagic/smartlead-mcp-server/issues)
- **SmartLead API**: [api.smartlead.ai](https://api.smartlead.ai)

---

## 🏆 Ready for Export!

Your SmartLead MCP Server package is now ready for distribution:

- **Package File**: `smartlead-mcp-by-leadmagic-1.6.1.tgz`
- **All Tools Implemented**: 116+ SmartLead API endpoints
- **Production Ready**: Comprehensive error handling and logging
- **MCP Compliant**: Works with Claude, Cursor, Windsurf, and more

The package can be installed globally, locally, or used directly with npx for maximum flexibility!