InboxAssure MCP Server

Comprehensive Model Context Protocol (MCP) server for the InboxAssure email marketing platform. This server provides full API coverage with 23 tools for managing campaigns, replies, and email accounts through AI assistants like Claude and Cursor.

Features

• 23 comprehensive tools covering the entire InboxAssure API
• Campaigns Management: Create, manage, and analyze email campaigns
• Replies Management: Handle incoming emails and compose responses
• Email Accounts: Manage sender accounts and configurations
• Multi-transport support: STDIO, HTTP, and SSE protocols
• Client compatibility: Works with Claude Desktop, Cursor, and other MCP clients
• Secure API key handling: Client-provided keys, no server-side storage

Prerequisites

• Node.js (version 18.x or later)
• npm (usually comes with Node.js)
• InboxAssure API key (starting with iak_)

Installation

1. Clone this repository:

   git clone https://github.com/your-org/inboxassure-mcp-server
   cd inboxassure-mcp-server

2. Install dependencies:

   npm install

Usage

STDIO Mode (Recommended for AI Assistants)

# Using npm script
npm run start:stdio -- --api-key YOUR_INBOXASSURE_API_KEY

# Or directly using node
node src/cli.js --stdio --api-key YOUR_INBOXASSURE_API_KEY

HTTP Server Mode

# Default port 3000
npm start -- --api-key YOUR_INBOXASSURE_API_KEY

# Custom port
npm start -- --api-key YOUR_INBOXASSURE_API_KEY --port 3001

The HTTP server provides:

• MCP Endpoint: http://localhost:PORT/mcp (POST requests)
• Health Check: http://localhost:PORT/health (GET requests)

Available Tools

Original Tools

• get_bison_hello - Test endpoint to verify API connectivity

📧 Campaigns API (11 tools)

1. list_campaigns - List all campaigns with filtering and pagination

   • Parameters: workspace_id, optional params (search, status, page, per_page)

2. create_campaign - Create a new email marketing campaign

   • Parameters: workspace_id, name, optional type

3. get_campaign_details - Get detailed campaign information

   • Parameters: workspace_id, campaign_id

4. pause_campaign - Temporarily pause a running campaign

   • Parameters: workspace_id, campaign_id

5. resume_campaign - Resume a paused campaign

   • Parameters: workspace_id, campaign_id

6. get_campaign_stats - Get performance metrics for date range

   • Parameters: workspace_id, campaign_id, start_date, end_date

7. get_campaign_leads - View leads in campaign with status

   • Parameters: workspace_id, campaign_id, optional params

8. create_campaign_schedule - Set up campaign sending schedule (days, times, timezone)

   • Parameters: workspace_id, campaign_id, start_time, end_time, timezone, day booleans

9. get_schedule_templates - Get predefined schedule templates for quick setup

   • Parameters: workspace_id

10. create_sequence_steps - Define email sequence steps for drip campaigns

    • Parameters: workspace_id, campaign_id, title, sequence_steps array

11. attach_lead_list - Import entire lead lists into campaigns

    • Parameters: workspace_id, campaign_id, lead_list_id

💬 Replies API (5 tools)

12. list_replies - Retrieve email replies with filtering

    • Parameters: workspace_id, optional params (search, status, folder, etc.)

13. get_reply_details - Get complete reply details and content

    • Parameters: workspace_id, reply_id

14. compose_new_email - Send standalone emails outside campaigns

    • Parameters: workspace_id, sender_email_id, to_emails, message, optional content_type, cc_emails, bcc_emails

15. reply_to_email - Respond to emails maintaining thread

    • Parameters: workspace_id, reply_id, sender_email_id, to_emails, message, optional content_type

16. get_conversation_thread - Get complete conversation history

    • Parameters: workspace_id, reply_id

👤 Email Accounts API (6 tools)

17. list_email_accounts - List configured email accounts

    • Parameters: workspace_id, optional params (search, page, per_page)

18. get_email_account_details - Get account configuration and stats

    • Parameters: workspace_id, email_id

19. update_email_account - Modify account settings

    • Parameters: workspace_id, email_id, optional daily_limit, name, email_signature

20. get_account_campaigns - See which campaigns use this email account

    • Parameters: workspace_id, email_id

21. get_account_replies - View replies received by this email account

    • Parameters: workspace_id, email_id

22. bulk_update_email_signatures - Update signatures across multiple accounts

    • Parameters: workspace_id, sender_email_ids array, email_signature

Total: 23 tools (1 original + 11 campaigns + 5 replies + 6 email accounts)

Client Configuration

For Claude Desktop

Add to your Claude MCP configuration:

{
  "mcpServers": {
    "InboxAssure": {
      "command": "node",
      "args": [
        "/path/to/inboxassure-mcp-server/src/cli.js",
        "--api-key=YOUR_INBOXASSURE_API_KEY",
        "--stdio"
      ]
    }
  }
}

For Cursor

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "InboxAssure Email Marketing": {
      "command": "node",
      "args": [
        "/full/path/to/src/cli.js",
        "--api-key=YOUR_INBOXASSURE_API_KEY",
        "--stdio"
      ]
    }
  }
}

Global NPM Installation (Coming Soon)

Once published to NPM:

{
  "mcpServers": {
    "InboxAssure": {
      "command": "npx",
      "args": [
        "-y",
        "inboxassure-mcp-server",
        "--api-key=YOUR_INBOXASSURE_API_KEY",
        "--stdio"
      ]
    }
  }
}

API Key Management

This server follows security best practices:

• Client-provided: API keys are provided via --api-key argument
• No server storage: Keys are never stored on the server
• Header extraction: Supports multiple header formats for compatibility
• Per-request authentication: Each API call uses the client's key

Development

Development Scripts

# Start with placeholder API key (update in package.json)
npm run dev
npm run dev:stdio

# Linting (placeholder)
npm run lint

Testing Locally

1. Start the server:

   node src/cli.js --api-key=YOUR_KEY --stdio

2. Send test JSON-RPC messages:

   {"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

Deployment

Production Deployment (PM2)

The project includes PM2 ecosystem configuration:

# Deploy to production server
ssh -i ~/.ssh/mcpx root@167.99.230.52 "cd /root/mcpx && git pull && pm2 restart all"

Docker Deployment

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY src/ ./src/
EXPOSE 3000
CMD ["node", "src/cli.js"]

API Documentation

The server integrates with the complete InboxAssure API:

• Base URL: https://bison.imnodev.com/api/
• Authentication: X-API-Key header with InboxAssure API key
• Endpoints: Campaigns, Replies, Email Accounts APIs

Common Parameters

• workspace_id: Your InboxAssure workspace identifier
• Pagination: page (default: 1), per_page (default: 15, max: 100)
• Filtering: search, status, folder parameters
• Date Format: ISO 8601 (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ)

Troubleshooting

Common Issues

1. "API key is required": Ensure --api-key is provided in client configuration
2. Connection errors: Verify API key format starts with iak_
3. Tools not appearing: Check client MCP configuration and restart client
4. Permission errors: Verify API key has appropriate workspace permissions

Debug Logging

The server provides extensive debug logging:

# Check server logs
tail -f /var/log/your-app/mcp-server.log

# Enable verbose debugging
DEBUG=* node src/cli.js --api-key=YOUR_KEY

Client Logs

• Windows: %APPDATA%\Claude\logs\mcp*.log
• macOS: ~/Library/Logs/Claude/mcp*.log

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Create an issue on GitHub
• Check the InboxAssure API documentation
• Review the MCP specification