Abstract API MCP Server

A Model Context Protocol (MCP) server that provides email and phone validation tools using Abstract API services. This server is built with FastMCP, making it easy to integrate validation capabilities into AI applications and workflows.

Overview

This MCP server exposes three main validation tools:

• Email Validation: Comprehensive email address validation and verification
• Phone Validation: Phone number validation for 190+ countries
• Email Reputation: Advanced email reputation analysis with security insights

Features

Email Validation

• Format validation
• Deliverability checking
• Domain verification
• SMTP validation
• Detection of disposable/role/catchall emails
• Quality scoring

Phone Validation

• International phone number validation
• Format standardization (international/local)
• Country and carrier identification
• Phone type detection (mobile, landline, etc.)
• Location information

Email Reputation

• Comprehensive deliverability analysis
• Quality scoring and risk assessment
• Sender and organization identification
• Domain security analysis (DMARC, SPF)
• Data breach history tracking
• Fraud and abuse detection

Prerequisites

• Python 3.11+
• uv (fast Python package installer)
• Abstract API key (get one at abstractapi.com)

Installation

Option 1: Using uv (Recommended)

2. Clone the repository:

git clone https://github.com/avivshafir/abstractapi-mcp-server
cd abstractapi-mcp-server

3. Create virtual environment and install dependencies:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install .

4. Set up environment variables:

cp .env.example .env
# Edit .env and add your Abstract API key

Option 2: Using traditional pip

1. Clone the repository:

git clone https://github.com/avivshafir/abstractapi-mcp-server
cd abstractapi-mcp-server

2. Create a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. Install dependencies:

pip install -r requirements.txt

4. Set up environment variables:

cp .env.example .env
# Edit .env and add your Abstract API key

Your .env file should contain:

ABSTRACT_API_KEY=your_abstract_api_key_here

Usage

Running the MCP Server

The server can be run in stdio mode for integration with MCP clients:

# With uv (if virtual environment is activated)
python server.py

# Or run directly with uv
uv run server.py

FastMCP Framework

This server is built using FastMCP, a Python framework that simplifies MCP server development. FastMCP provides:

• Automatic tool registration: Functions decorated with @mcp.tool() are automatically exposed as MCP tools
• Type safety: Full type hints and validation
• Easy async support: Native async/await support
• Simplified server setup: Minimal boilerplate code

Key FastMCP Concepts

from mcp.server.fastmcp import FastMCP

# Initialize the server
mcp = FastMCP("abstract_api")

# Register a tool
@mcp.tool()
async def my_tool(param: str) -> dict:
    """Tool description for AI clients"""
    return {"result": param}

# Run the server
mcp.run(transport="stdio")

Available Tools

1. Email Validation (verify_email)

Validates email addresses and returns comprehensive information.

Parameters:

• email (str): Email address to validate

Example Response:

{
  "email": "user@example.com",
  "deliverability": "DELIVERABLE",
  "quality_score": "0.99",
  "is_valid_format": {"value": true, "text": "TRUE"},
  "is_free_email": {"value": false, "text": "FALSE"},
  "is_disposable_email": {"value": false, "text": "FALSE"},
  "is_role_email": {"value": false, "text": "FALSE"},
  "is_catchall_email": {"value": false, "text": "FALSE"},
  "is_mx_found": {"value": true, "text": "TRUE"},
  "is_smtp_valid": {"value": true, "text": "TRUE"}
}

2. Phone Validation (validate_phone)

Validates phone numbers from 190+ countries.

Parameters:

• phone (str): Phone number to validate
• country (str, optional): ISO country code for context

Example Response:

{
  "phone": "14152007986",
  "valid": true,
  "format": {
    "international": "+14152007986",
    "local": "(415) 200-7986"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "California",
  "type": "mobile",
  "carrier": "T-Mobile USA, Inc."
}

3. Email Reputation (check_email_reputation)

Provides comprehensive email reputation analysis including security insights and breach history.

Parameters:

• email (str): Email address to analyze

Example Response:

{
  "email_address": "benjamin.richard@abstractapi.com",
  "email_deliverability": {
    "status": "deliverable",
    "status_detail": "valid_email",
    "is_format_valid": true,
    "is_smtp_valid": true,
    "is_mx_valid": true,
    "mx_records": ["gmail-smtp-in.l.google.com", "..."]
  },
  "email_quality": {
    "score": 0.8,
    "is_free_email": false,
    "is_username_suspicious": false,
    "is_disposable": false,
    "is_catchall": true,
    "is_subaddress": false,
    "is_role": false,
    "is_dmarc_enforced": true,
    "is_spf_strict": true,
    "minimum_age": 1418
  },
  "email_sender": {
    "first_name": "Benjamin",
    "last_name": "Richard",
    "email_provider_name": "Google",
    "organization_name": "Abstract API",
    "organization_type": "company"
  },
  "email_domain": {
    "domain": "abstractapi.com",
    "domain_age": 1418,
    "is_live_site": true,
    "registrar": "NAMECHEAP INC",
    "date_registered": "2020-05-13",
    "date_expires": "2025-05-13",
    "is_risky_tld": false
  },
  "email_risk": {
    "address_risk_status": "low",
    "domain_risk_status": "low"
  },
  "email_breaches": {
    "total_breaches": 2,
    "date_first_breached": "2018-07-23T14:30:00Z",
    "date_last_breached": "2019-05-24T14:30:00Z",
    "breached_domains": [
      {"domain": "apollo.io", "date_breached": "2018-07-23T14:30:00Z"},
      {"domain": "canva.com", "date_breached": "2019-05-24T14:30:00Z"}
    ]
  }
}

Integration with MCP Clients

Add this server to your mcp configuration:

{
  "mcpServers": {
    "abstract-api": {
      "command": "uv",
      "args": ["run", "/path/to/mcp-abstract-api/server.py"],
      "env": {
        "ABSTRACT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Alternatively, if you prefer to use the traditional approach:

{
  "mcpServers": {
    "abstract-api": {
      "command": "python",
      "args": ["/path/to/mcp-abstract-api/server.py"],
      "env": {
        "ABSTRACT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Other MCP Clients

This server follows the standard MCP protocol and can be integrated with any MCP-compatible client. The server communicates via stdio transport.

Error Handling

The server includes comprehensive error handling:

• API Key Validation: Checks for missing API keys
• HTTP Error Handling: Proper handling of API response errors
• Input Validation: Type checking and parameter validation
• Graceful Degradation: Meaningful error messages for debugging

API Rate Limits

Abstract API has different rate limits based on your plan:

• Free plans: 1 request per second
• Paid plans: Higher rate limits available

Each API call counts as one credit, regardless of whether the validation succeeds or fails.

Development

Project Structure

mcp-abstract-api/
├── server.py          # Main MCP server implementation
├── .env              # Environment variables (not in repo)
├── .env.example      # Environment template
├── requirements.txt  # Python dependencies (pip format)
├── uv.lock           # uv lock file for reproducible builds
├── pyproject.toml    # Project configuration
├── README.md         # This file
└── LICENSE          # MIT License

Adding New Tools

To add new Abstract API tools:

1. Add the API endpoint URL as a constant
2. Create a new function decorated with @mcp.tool()
3. Add comprehensive docstring with parameter and return descriptions
4. Implement error handling following the existing pattern

Example:

@mcp.tool()
async def new_validation_tool(param: str) -> dict[str, Any]:
    """
    Description of what this tool does.
    
    Args:
        param (str): Description of parameter
        
    Returns:
        dict[str, Any]: Description of return value
    """
    # Implementation here
    pass

Contributing

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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues related to:

• This MCP server: Open an issue in this repository
• Abstract API: Contact Abstract API support
• FastMCP framework: Check the FastMCP documentation

Acknowledgments

• Abstract API for providing the validation services
• FastMCP for the MCP server framework
• Model Context Protocol for the protocol specification