email-insights-mcp-server

opportify/email-insights-mcp-server

3.2

If you are the rightful owner of email-insights-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Email Insights MCP Server provides access to the Opportify Email Insights API, enabling email validation and detailed analysis of email addresses.

Tools
1
Resources
0
Prompts
0

Email Insights MCP Server

A Model Context Protocol (MCP) server that provides access to the Opportify Email Insights API. This server allows you to validate email addresses and get detailed information about their deliverability, provider, and risk assessment.

Features

  • Email Validation: Validate email syntax and format
  • Deliverability Check: Determine if an email address is deliverable
  • Provider Detection: Identify email providers (Gmail, Outlook, etc.)
  • Email Type Classification: Detect free, disposable, private, or unknown email types
  • Risk Assessment: AI-driven risk scoring (200-1000 scale)
  • Auto-correction: Automatically correct common email misspellings
  • DNS Verification: Check MX records and domain reachability
  • Catch-all Detection: Identify domains that accept all emails

Prerequisites

  • Node.js (version 18 or higher)
  • npm or yarn package manager
  • Opportify API key (get one from Opportify)

Installation

1. Clone and Setup the Repository

git clone git@github.com:opportify/email-insights-mcp-server.git
cd email-insights-mcp-server

2. Install Dependencies

npm install

3. Build the Project

npm run build

4. Configure API Key

Create a .env file in the project root:

cp .env.example .env

Edit the .env file and add your Opportify API key:

OPPORTIFY_API_KEY=your_actual_api_key_here

Alternatively, set the environment variable globally:

export OPPORTIFY_API_KEY="your_actual_api_key_here"

VSCode Configuration with GitHub Copilot

1. Install Required Extensions

First, ensure you have the following VSCode extensions installed:

  • GitHub Copilot - AI-powered code completion
  • MCP Client (if available) or configure manually

2. Configure MCP Server in VSCode

Option A: Using VSCode Settings (Recommended)
  1. Open VSCode Settings (Cmd+, on Mac or Ctrl+, on Windows/Linux)
  2. Search for "MCP" or "Model Context Protocol"
  3. Add the email insights server configuration:
{
  "mcp.servers": {
    "email-insights": {
      "command": "node",
      "args": ["/absolute/path/to/email-insights-mcp-server/dist/index.js"],
      "env": {
        "OPPORTIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}
Option B: Using settings.json File

  1. Open your VSCode settings file:

    • Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
    • Type "Preferences: Open Settings (JSON)"
    • Select the option

  2. Add the MCP server configuration:

{
  "mcp.servers": {
    "email-insights": {
      "command": "node",
      "args": ["/Users/your-username/path/to/email-insights-mcp-server/dist/index.js"],
      "env": {
        "OPPORTIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}
Option C: Using Workspace Configuration

For project-specific configuration, create or edit .vscode/settings.json in your workspace:

{
  "mcp.servers": {
    "email-insights": {
      "command": "node",
      "args": ["./node_modules/email-insights-mcp-server/dist/index.js"],
      "env": {
        "OPPORTIFY_API_KEY": "your_api_key_here"
      }
    }
  }
}

3. Alternative: Global MCP Configuration

If you prefer a global configuration, create a file at ~/.config/mcp/servers.json:

{
  "email-insights": {
    "command": "node",
    "args": ["/absolute/path/to/email-insights-mcp-server/dist/index.js"],
    "env": {
      "OPPORTIFY_API_KEY": "your_api_key_here"
    }
  }
}

4. GitHub Copilot Integration

Once configured, GitHub Copilot can use the email insights server:

  1. Restart VSCode after adding the configuration
  2. Open a file where you want to use email validation
  3. Ask Copilot to validate emails using natural language:

5. Verify Configuration

To verify the server is working:

  1. Open VSCode terminal

  2. Run the test script:

    cd /path/to/email-insights-mcp-server
OPPORTIFY_API_KEY=your_key node test.js

  3. Check VSCode output panel for MCP server logs

Usage Examples

Basic Usage with Copilot

Once configured, you can use the email insights server through GitHub Copilot:

Example 1: Email Validation
Prompt: "Validate the email address john.doe@company.com"

Copilot will use the MCP server to validate the email and provide results like:

  • Format validity
  • Provider information
  • Deliverability status
  • Risk assessment
Example 2: Bulk Email Validation
Prompt: "Check these emails for deliverability:
- user1@gmail.com
- invalid-email@fake-domain.xyz
- admin@company.com"
Example 3: Risk Analysis
Prompt: "Analyze the risk level of suspicious@temp-mail.com"

Direct API Usage

You can also run the server directly for testing:

# Start the server
npm start

# The server will listen on stdin/stdout for MCP protocol messages

Command Line Testing

Use the included test script:

# Set your API key and run the test
OPPORTIFY_API_KEY=your_key node test.js
analyze_email

Validates an email address and returns detailed information about its deliverability, provider, and risk assessment.

Parameters:

  • email (required): The email address to analyze
  • enableAI (optional): Enable AI-driven risk analysis (default: true)
  • enableAutoCorrection (optional): Enable automatic email correction (default: true)

Example:

{
  "email": "user@example.com",
  "enableAI": true,
  "enableAutoCorrection": true
}

Response:

{
  "emailAddress": "user@example.com",
  "emailProvider": "Google",
  "emailType": "free",
  "isFormatValid": true,
  "emailCorrection": "user@example.com",
  "isDeliverable": "yes",
  "isCatchAll": false,
  "isMailboxFull": false,
  "isReachable": true,
  "emailDNS": {
    "mx": ["mx1.example.com", "mx2.example.com"]
  },
  "riskReport": {
    "score": 850,
    "level": "highest",
    "baseAnalysis": ["instance-bounce", "future-bounce", "fraud"]
  }
}

Available Tools

analyze_email

Validates an email address and returns detailed information about its deliverability, provider, and risk assessment.

Parameters:

  • email (required): The email address to analyze
  • enableAI (optional): Enable AI-driven risk analysis (default: true)
  • enableAutoCorrection (optional): Enable automatic email correction (default: true)

Example:

{
  "email": "user@example.com",
  "enableAI": true,
  "enableAutoCorrection": true
}

Response:

{
  "emailAddress": "user@example.com",
  "emailProvider": "Google",
  "emailType": "free",
  "isFormatValid": true,
  "emailCorrection": "user@example.com",
  "isDeliverable": "yes",
  "isCatchAll": false,
  "isMailboxFull": false,
  "isReachable": true,
  "emailDNS": {
    "mx": ["mx1.example.com", "mx2.example.com"]
  },
  "riskReport": {
    "score": 850,
    "level": "highest",
    "baseAnalysis": ["instance-bounce", "future-bounce", "fraud"]
  }
}

Troubleshooting

Common Issues

  1. "OPPORTIFY_API_KEY environment variable is required"

    • Solution: Make sure you've set the API key in your environment or .env file

  2. Server not starting in VSCode

    • Check that the path to dist/index.js is correct and absolute
    • Verify the server builds successfully with npm run build
    • Check VSCode output panel for error messages

  3. Permission denied errors

    • Ensure Node.js has execute permissions
    • Try running chmod +x dist/index.js

  4. API errors

    • Verify your Opportify API key is valid
    • Check your internet connection
    • Review API usage limits

Debug Mode

To run the server with debug output:

DEBUG=* npm start

Or set debug environment variable in your VSCode configuration:

{
  "mcp.servers": {
    "email-insights": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "OPPORTIFY_API_KEY": "your_api_key_here",
        "DEBUG": "mcp:*"
      }
    }
  }
}

Development

Building

npm run build

Development Mode

npm run dev

Testing

npm test

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

Support

  • Issues: Report bugs or request features on GitHub Issues
  • Documentation: Visit Opportify API Documentation
  • Community: Join discussions in the repository

License

MIT License - see LICENSE file for details.