abstractapi-mcp-server by avivshafir - MCP Server

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)

Clone the repository:

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

Create virtual environment and install dependencies:

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

Set up environment variables:

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

Option 2: Using traditional pip

Clone the repository:

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

Create a virtual environment:

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

Install dependencies:

pip install -r requirements.txt

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:

Add the API endpoint URL as a constant
Create a new function decorated with @mcp.tool()
Add comprehensive docstring with parameter and return descriptions
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

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

This project is licensed under the MIT License - see the 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

avivshafir/abstractapi-mcp-server