mailmodo-mcp

This is a TypeScript project that implements a Message Control Protocol (MCP) server for Mailmodo integration with Claude Desktop and other MCP supported client.

Prerequisites

• Node.js (v20 or higher recommended)
• npm (comes with Node.js)

Installation

1. Clone the repository:

git clone https://github.com/mailmodo/mailmodo-mcp.git
cd mailmodo-mcp

2. Install dependencies:

npm install

Building the Project

To compile the TypeScript code to JavaScript, run:

npm run build

This will create a dist directory containing the compiled JavaScript files.

Running the Project

After building, you can run the project using:

node dist/index.js

Or use the npm script:

npm start

Claude Desktop Configuration

Local Run from Code

To configure this project with Claude Desktop, add the following configuration to your Claude Desktop settings:

{
  "mcpServers": {
    "mailmodo": {
      "command": "node",
      "args": [
        "/path/to/your/mailmodo-mcp/dist/index.js"
      ]
    }
  }
}

Run from docker image

{
  "mcpServers": {
    "mailmodo": {
      "command": "docker",
      "args": [
        "run",
        "--platform", 
        "linux/amd64",
        "-i",
        "--rm",
        "-e",
        "MAILMODO_API_KEY",
        "avneesh001/mailmodo-mcp"
      ],
      "env": {
        "MAILMODO_API_KEY": "<GET MAILMODO KEY from https://manage.mailmodo.com/app/settings/apikey and insert here>"
      }
    }
  }
}

Run from npx

{
  "mcpServers": {
    "mailmodo": {
      "command": "npx",
      "args": [
        "-y",
        "@mailmodo/mcp"
      ],
      "env": {
        "MAILMODO_API_KEY": "<GET MAILMODO KEY from https://manage.mailmodo.com/app/settings/apikey and insert here>"
      }
    }
  }
}

Connect via Remote Server

{
  "mcpServers": {
    "mailmodo": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.app.mailmodo.com/mcp",
        "--header",
        "mmApiKey:${MAILMODO_API_KEY}"
      ],
      "env": {
        "MAILMODO_API_KEY": "<GET MAILMODO KEY from https://manage.mailmodo.com/app/settings/apikey and insert here>"
      }
    }
  }
}

Make sure to adjust the file path in the args array to match your local project directory.

Development

To run the project in development mode with automatic recompilation:

1. Install ts-node and nodemon as dev dependencies:

npm install --save-dev ts-node nodemon

2. Add a dev script to your package.json:

{
  "scripts": {
    "dev": "nodemon src/index.ts",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

3. Run the development server:

npm run dev

Project Structure

mailmodo-mcp/
├── src/             # TypeScript source files
├── dist/            # Compiled JavaScript files
├── package.json     # Project dependencies and scripts
└── tsconfig.json    # TypeScript configuration

Tools and Resources

The Mailmodo MCP server provides several tools and resources for interacting with Mailmodo's functionality. Here's a comprehensive list:

Resources

1. Mailmodo Templates (mailmodo://templates)

   • Returns a list of all available email templates in JSON format
   • MIME Type: application/json

2. Mailmodo Campaigns (mailmodo://campaigns)

   • Returns a list of all campaigns in JSON format
   • MIME Type: application/json

3. Mailmodo Contact Lists (mailmodo://contact-lists)

   • Returns all contact lists in JSON format
   • MIME Type: application/json

Tools

1. User Details

   • Name: userDetails
   • Description: Get all details of a contact
   • Parameters:
     • email (string): Email address of the contact

2. Campaign Report Tool

   • Name: MailmodoCampainReportTool
   • Description: Get campaign reports including open, click, and submission counts
   • Parameters:
     • campaignId (UUID): ID of the campaign
     • fromDate (YYYY-MM-DD): Start date for the report
     • toDate (YYYY-MM-DD): End date for the report

3. Current DateTime

   • Name: currentDateTime
   • Description: Get current date and time
   • Parameters: None

4. Send Event

   • Name: sendEvent
   • Description: Send custom events with email and event properties
   • Parameters:
     • email (string): Contact's email address
     • event_name (string): Name of the event
     • ts (number, optional): Timestamp
     • event_properties (object, optional): Additional event properties

5. Contact List Management

   • Add Contact to List

     • Name: addContactToList
     • Description: Add a single contact to a list
     • Parameters:
       • email (string): Contact's email
       • listName (string): Name of the list
       • data (object, optional): Contact properties
       • Various optional fields for contact metadata

   • Bulk Add Contacts

     • Name: addBulkContactToList
     • Description: Add multiple contacts to a list in a single operation
     • Parameters:
       • listName (string): Name of the list
       • values (array): Array of contact objects

   • Remove Contact from List

     • Name: removeContactFromList
     • Description: Remove a contact from a specific list
     • Parameters:
       • email (string): Contact's email
       • listName (string): Name of the list

6. Contact Status Management

   • Unsubscribe Contact

     • Name: unsubscribeContact
     • Description: Unsubscribe or suppress a contact
     • Parameters:
       • email (string): Contact's email

   • Resubscribe Contact

     • Name: resubscribeContact
     • Description: Resubscribe a previously unsubscribed contact
     • Parameters:
       • email (string): Contact's email

   • Archive Contact

     • Name: archiveContact
     • Description: Permanently archive a contact
     • Parameters:
       • email (string): Contact's email

7. Campaign Management

   • Send Email Campaign

     • Name: sendEmailToCampaign
     • Description: Trigger an email campaign with personalization
     • Parameters:
       • campaignId (string): Campaign ID
       • email (string): Recipient's email
       • Various optional parameters for customization

   • Broadcast Campaign

     • Name: broadcastCampaignToList
     • Description: Trigger campaigns to an entire contact list
     • Parameters:
       • campaignId (string): Campaign ID
       • listId (string): Target list ID
       • Optional parameters for campaign customization

License

MIT License