MCP 服务器

smartlead-mcp-server-sse

An MCP server that enables AI agents to manage Smartlead campaigns, including creating campaigns, updating schedules, managing email sequences, and adding leads, all over SSE.

README

One Click Deploy Smartlead MCP Server with SSE

This is a Model Context Protocol (MCP) server, enhanced with Supergateway, that allows AI agents to interact with the Smartlead campaign management API over Server-Sent Events (SSE).

Deployment

One-Click Deploy to Railway

Click the "Deploy on Railway" button above. Railway will guide you through creating a new project from this template and configuring the necessary environment variables (see "Configuration" below).

Docker Deployment (Manual / Local Testing)

The Dockerfile in this repository builds the smartlead-mcp-server and runs it with Supergateway.

Build the Docker Image:

docker build -t smartlead-mcp-server-supergateway .

Run the Docker Container:

# Replace YOUR_SMARTLEAD_API_KEY with your actual Smartlead API key
# The server will be accessible via SSE on http://localhost:8001/sse (host port 8001 mapped to container port 8000)
docker run --rm -it -p 8001:8000 \
  -e PORT=8000 \
  -e SMARTLEAD_API_KEY="YOUR_SMARTLEAD_API_KEY" \
  -e SMARTLEAD_API_URL="https://server.smartlead.ai/api/v1" \
  -e DEBUG=true \
  smartlead-mcp-server-supergateway

Supergateway provides default paths: /sse for the event stream and /message for posting messages. The health check is at /healthz.

Configuration

The server requires the following environment variables. When deploying to Railway, you will be prompted for these. For local Docker runs, pass them using the -e flag.

SMARTLEAD_API_KEY: Your Smartlead API key. Required and should be treated as a secret.
SMARTLEAD_API_URL (Optional): Custom Smartlead API URL. Defaults to https://server.smartlead.ai/api/v1.
SMARTLEAD_RETRY_MAX_ATTEMPTS (Optional): Maximum retry attempts for API calls. Default: 3.
SMARTLEAD_RETRY_INITIAL_DELAY (Optional): Initial delay in milliseconds for retries. Default: 1000.
SMARTLEAD_RETRY_MAX_DELAY (Optional): Maximum delay in milliseconds for retries. Default: 10000.
SMARTLEAD_RETRY_BACKOFF_FACTOR (Optional): Backoff factor for retry delays. Default: 2.
DEBUG (Optional): Set to true for verbose logging from the server and Supergateway, or false for production. Default: false.
PORT (Set by Railway/Container): The port Supergateway will listen on inside the container. The Dockerfile default is 8000. When running locally with Docker, you map a host port to this container port (e.g., -p 8001:8000).

Connecting to the Server (Client Integration)

Once the smartlead-mcp-server is running (e.g., deployed on Railway or locally in Docker), it exposes an MCP interface over Server-Sent Events (SSE).

The Supergateway instance typically makes the MCP server available at:

SSE Stream: http://<server_address>:<port>/sse
Message Endpoint (if used): http://<server_address>:<port>/message

(If deployed on Railway, <server_address>:<port> will be your public Railway URL, e.g., https://my-smartlead-mcp.up.railway.app)

Direct SSE Connection (Preferred for SSE-aware clients): If your MCP client (e.g., your AI agent's framework) natively supports connecting to an MCP server via an SSE URL, configure it accordingly.

Example mcp.json configuration for direct SSE:

{
  "mcpServers": {
    "smartlead_remote_sse": {
      "url": "https://YOUR_RAILWAY_DEPLOYMENT_URL/sse", // Replace with your actual Railway SSE URL
      "disabled": false,
      "alwaysAllow": [
        "smartlead_create_campaign",
        "smartlead_update_campaign_schedule",
        "smartlead_update_campaign_settings",
        "smartlead_get_campaign",
        "smartlead_list_campaigns",
        "smartlead_save_campaign_sequence",
        "smartlead_get_campaign_sequence",
        "smartlead_update_campaign_sequence",
        "smartlead_delete_campaign_sequence",
        "smartlead_add_email_account_to_campaign",
        "smartlead_update_email_account_in_campaign",
        "smartlead_delete_email_account_from_campaign",
        "smartlead_add_lead_to_campaign",
        "smartlead_update_lead_in_campaign",
        "smartlead_delete_lead_from_campaign"
      ],
      "timeout": 300
    }
  }
}

Using Supergateway on the Client-Side (SSE-to-stdio bridge): If your MCP client expects to launch a local command that communicates via stdio (standard input/output), you can use another Supergateway instance locally on the client's machine to bridge the remote SSE connection back to stdio.

Example mcp.json or similar client configuration for the bridge:

{
  "mcpServers": {
    "smartlead_remote_via_bridge": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse", "https://YOUR_RAILWAY_DEPLOYMENT_URL", // Replace with your actual Railway base URL (without /sse)
        // Supergateway will append /sse by default
        "--logLevel", "info" // Optional: for debugging Supergateway on the client
      ],
      "disabled": false,
      "alwaysAllow": [ /* ... list of Smartlead tools as above ... */ ]
    }
  }
}

Original Features (from base Smartlead MCP Server)

Create new campaigns
Update campaign schedule settings
Update campaign general settings
Get campaign details
List all campaigns with filtering options
Manage campaign email sequences (save, get, update, delete)
Manage email accounts in campaigns (add, update, delete)
Manage leads in campaigns (add, update, delete)

Local Development Setup (without Docker/Supergateway)

Clone the repository
Install dependencies:
```
npm install
```
Create a .env file (e.g., from .env.example) and add your Smartlead API key:
```
SMARTLEAD_API_KEY=your_api_key_here
```
Build the project:
```
npm run build
```
Start the server directly (stdio mode):
```
npm start 
# or node dist/index.js
```

Example Local `mcp.json` for stdio mode (original setup)

{
  "mcpServers": {
    "smartlead_local_stdio": {
      "command": "node",
      // Adjust path to your local built server:
      "args": ["FULL_PATH_TO_YOUR_PROJECT/smartlead-mcp-server/dist/index.js"], 
      "env": {
        "SMARTLEAD_API_KEY": "your_api_key_here"
      },
      "disabled": false,
      "alwaysAllow": [ /* ... list of Smartlead tools ... */ ]
    }
  }
}

Available Tools

(This section lists the tools provided by the server. Refer to the original README sections for detailed parameters, or use MCP introspection if available.)