Local MCP Server

Tomba Local MCP Tools

MCP Tools

This document provides detailed information about all thirteen tools available in the Tomba MCP Server. Each tool offers specific email intelligence capabilities with comprehensive input validation and structured output.

Tools Overview

Tool	Purpose	Input	Output Type
domain_search	Find emails by domain	Domain name + options	Email list with metadata
email_finder	Generate email from name + domain	First/last name + domain	Single email with confidence
email_verifier	Verify email deliverability	Email address	Verification status + score
email_enrichment	Enrich email with contact data	Email address	Complete contact profile
email_count	Get total email counts for domain	Domain name	Email count statistics
author_finder	Find author emails from articles	Article URL	Author contact list
linkedin_finder	Find emails from LinkedIn	LinkedIn profile URL	Contact with verification
phone_finder	Find phone numbers	Email/domain/LinkedIn	Phone numbers with details
phone_validator	Validate phone numbers	Phone number	Validation results + carrier
technology_finder	Discover tech stacks	Domain name	Technology list + categories
similar_finder	Find similar companies	Domain name	Similar domain list
companies_search	Search companies by query	Natural language query	Company list with filters

---

Prompts (16 pre-built workflows)

Contact Discovery & Enrichment

• find_contact - Find complete contact info for a person
• enrich_lead - Enrich a lead with all available data
• prospect_enrichment - Enrich company prospects with comprehensive data

Email & Phone Verification

• verify_email_list - Batch verify email addresses
• finder_phone - Find phone numbers for contacts
• validate_phone - Validate a phone number

Company & Market Research

• research_company - Research company contacts and structure
• domain_insights - Get comprehensive insights about a domain including email count and technology
• bulk_domain_research - Research multiple domains for email counts and basic information
• market_research - Research companies in a specific market segment
• industry_analysis - Analyze companies within a specific industry and location

Competitive Intelligence

• competitor_analysis - Analyze competitors using similar domains and technology
• technology_audit - Comprehensive technology audit of a website

Lead Generation & Targeting

• find_target_companies - Find companies matching specific criteria using natural language search
• lead_generation - Generate leads by finding companies and their contacts
• find_journalists - Find journalist contacts from articles

---

Domain Search

Purpose: Discover all email addresses associated with a specific domain name.

Input Schema

Code
 
{
    "domain": "string (required)",
    "limit": "number (optional, default: 10)",
    "offset": "number (optional, default: 0)",
    "type": "string (optional: 'personal' | 'generic')",
    "sources": "boolean (optional, default: true)"
}

Parameters

Parameter	Type	Required	Description	Example
domain	string	Yes	Target domain name	"github.com"
limit	number	No	Max results to return (1-100)	25
offset	number	No	Results to skip for pagination	0
type	string	No	Filter by email type	"personal"
sources	boolean	No	Include source information	true

Example Usage

Code
 
// MCP Request
{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "domain_search",
        "arguments": {
            "domain": "github.com",
            "limit": 10,
            "type": "personal",
            "sources": true
        }
    }
}

Response Format

Code
 
{
    "domain": "github.com",
    "emails": [
        {
            "email": "john.doe@github.com",
            "first_name": "John",
            "last_name": "Doe",
            "position": "Senior Developer",
            "department": "Engineering",
            "type": "personal",
            "confidence": 95,
            "sources": [
                {
                    "uri": "https://github.com/about",
                    "website_piece": "team",
                    "extracted_on": "2024-01-15",
                    "last_seen_on": "2024-01-15",
                    "still_on_page": true
                }
            ]
        }
    ],
    "total": 147,
    "limit": 10,
    "offset": 0
}

Use Cases

• Lead generation for sales teams
• Competitive intelligence research
• Contact discovery for partnerships
• Email list building for marketing

---

Email Finder

Purpose: Generate the most likely email address for a person based on their name and company domain.

Input Schema

Code
 
{
    "domain": "string (required)",
    "firstName": "string (required)",
    "lastName": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
domain	string	Yes	Company domain	"microsoft.com"
firstName	string	Yes	Person's first name	"Satya"
lastName	string	Yes	Person's last name	"Nadella"

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
        "name": "email_finder",
        "arguments": {
            "domain": "microsoft.com",
            "firstName": "Satya",
            "lastName": "Nadella"
        }
    }
}

Response Format

Code
 
{
    "email": "satya.nadella@microsoft.com",
    "score": 98,
    "first_name": "Satya",
    "last_name": "Nadella",
    "full_name": "Satya Nadella",
    "gender": "male",
    "country": "US",
    "position": "CEO",
    "twitter": "@satyanadella",
    "linkedin": "https://linkedin.com/in/satya-nadella",
    "phone_number": null,
    "company": "Microsoft Corporation",
    "sources": [
        {
            "uri": "https://microsoft.com/leadership",
            "website_piece": "executive-team",
            "extracted_on": "2024-01-10",
            "last_seen_on": "2024-01-15",
            "still_on_page": true
        }
    ]
}

Use Cases

• Sales prospecting with known contacts
• Recruiting specific individuals
• Journalist source identification
• Partnership outreach

---

Email Verifier

Purpose: Verify email address deliverability and check if it exists in Tomba's database.

Input Schema

Code
 
{
    "email": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
email	string	Yes	Email address to verify	"test@example.com"

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
        "name": "email_verifier",
        "arguments": {
            "email": "satya.nadella@microsoft.com"
        }
    }
}

Response Format

Code
 
{
    "email": {
        "email": "satya.nadella@microsoft.com",
        "gibberish": false,
        "disposable": false,
        "webmail": false,
        "result": "deliverable",
        "score": 95
    },
    "sources": [
        {
            "uri": "https://microsoft.com/leadership",
            "website_piece": "executive-bio",
            "extracted_on": "2024-01-10",
            "last_seen_on": "2024-01-15",
            "still_on_page": true
        }
    ]
}

Verification Results

Result	Description
deliverable	Email exists and can receive messages
undeliverable	Email doesn't exist or bounces
risky	Email exists but may have issues
unknown	Cannot determine deliverability

Use Cases

• Email list cleaning before campaigns
• Lead qualification and scoring
• Contact database maintenance
• Fraud prevention and validation

---

Email Enrichment

Purpose: Get comprehensive contact information and social profiles for an email address.

Input Schema

Code
 
{
    "email": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
email	string	Yes	Email to enrich	"contact@company.com"

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
        "name": "email_enrichment",
        "arguments": {
            "email": "satya.nadella@microsoft.com"
        }
    }
}

Response Format

Code
 
{
    "email": "satya.nadella@microsoft.com",
    "first_name": "Satya",
    "last_name": "Nadella",
    "full_name": "Satya Nadella",
    "gender": "male",
    "country": "United States",
    "position": "Chief Executive Officer",
    "twitter": "satyanadella",
    "linkedin": "https://linkedin.com/in/satya-nadella",
    "phone_number": "+1-425-882-8080",
    "company": "Microsoft Corporation",
    "industry": "Technology",
    "website": "microsoft.com"
}

Use Cases

• CRM data enrichment
• Lead scoring and qualification
• Personalized outreach preparation
• Contact profile completion

---

Author Finder

Purpose: Extract email addresses of authors from article URLs.

Input Schema

Code
 
{
    "url": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
url	string	Yes	Article or blog post URL	"https://example.com/article"

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
        "name": "author_finder",
        "arguments": {
            "url": "https://github.blog/2024-01-15-new-features/"
        }
    }
}

Response Format

Code
 
{
    "emails": [
        {
            "email": "author@github.com",
            "first_name": "Jane",
            "last_name": "Smith",
            "position": "Technical Writer",
            "twitter": "janesmith_dev",
            "linkedin": "https://linkedin.com/in/janesmith"
        },
        {
            "email": "editor@github.com",
            "first_name": "Mike",
            "last_name": "Johnson",
            "position": "Content Editor",
            "twitter": "mikejohnson",
            "linkedin": "https://linkedin.com/in/mikejohnson"
        }
    ]
}

Use Cases

• Journalist contact discovery
• Guest posting outreach
• Expert source identification
• Content collaboration

---

LinkedIn Finder

Purpose: Find email addresses associated with LinkedIn profile URLs.

Input Schema

Code
 
{
    "url": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
url	string	Yes	LinkedIn profile URL	"https://linkedin.com/in/username"

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
        "name": "linkedin_finder",
        "arguments": {
            "url": "https://linkedin.com/in/satya-nadella"
        }
    }
}

Response Format

Code
 
{
    "email": "satya.nadella@microsoft.com",
    "first_name": "Satya",
    "last_name": "Nadella",
    "full_name": "Satya Nadella",
    "country": "United States",
    "gender": "male",
    "position": "Chief Executive Officer",
    "twitter": "satyanadella",
    "phone_number": null,
    "company": "Microsoft",
    "verification": {
        "date": "2024-01-15",
        "signature": "verified_profile_abc123"
    }
}

Use Cases

• Sales prospecting from LinkedIn
• Recruiting pipeline development
• Professional networking
• Contact verification from social profiles

---

Use Cases

• Market research and analysis
• Competitive intelligence gathering
• Partnership opportunity identification
• Industry mapping and analysis

---

Phone Finder

Purpose: Search for phone numbers based on email address, domain, or LinkedIn profile.

Input Schema

Code
 
{
    "email": "string (optional)",
    "domain": "string (optional)",
    "linkedin": "string (optional)"
}

Note: At least one parameter is required.

Parameters

Parameter	Type	Required	Description	Example
email	string	No*	Email address	"contact@company.com"
domain	string	No*	Company domain	"company.com"
linkedin	string	No*	LinkedIn profile URL	"https://linkedin.com/in/user"

*At least one parameter is required.

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 8,
    "method": "tools/call",
    "params": {
        "name": "phone_finder",
        "arguments": {
            "email": "satya.nadella@microsoft.com"
        }
    }
}

Response Format

Code
 
{
    "phone_number": "+1-425-882-8080",
    "country": "United States",
    "local_format": "(425) 882-8080",
    "intl_format": "+1 425 882 8080",
    "carrier": "Verizon",
    "line_type": "landline"
}

Use Cases

• Multi-channel contact strategies
• Lead enrichment with phone data
• Customer service contact verification
• Sales outreach diversification

---

Phone Validator

Purpose: Validate phone numbers and retrieve carrier information.

Input Schema

Code
 
{
    "phone": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
phone	string	Yes	Phone number to validate	"+1-425-882-8080"

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 9,
    "method": "tools/call",
    "params": {
        "name": "phone_validator",
        "arguments": {
            "phone": "+14258828080"
        }
    }
}

Response Format

Code
 
{
    "phone_number": "+14258828080",
    "valid": true,
    "country": "United States",
    "country_code": "US",
    "local_format": "(425) 882-8080",
    "intl_format": "+1 425 882 8080",
    "carrier": "Verizon Business",
    "line_type": "landline",
    "is_mobile": false
}

Validation Results

Field	Description
valid	Whether the phone number is valid
country	Country name
country_code	ISO country code
local_format	Local formatting
intl_format	International formatting
carrier	Telecom carrier name
line_type	"mobile", "landline", or "voip"
is_mobile	Boolean indicating mobile number

Use Cases

• Contact data validation
• SMS campaign preparation
• Fraud prevention
• Call routing optimization

---

Email Count

Purpose: Get total email count available in Tomba's database for a specific domain.

Input Schema

Code
 
{
    "domain": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
domain	string	Yes	Target domain name	"stripe.com"

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 10,
    "method": "tools/call",
    "params": {
        "name": "email_count",
        "arguments": {
            "domain": "stripe.com"
        }
    }
}

Response Format

Code
 
{
    "total": 347,
    "personal": 312,
    "generic": 35,
    "department": {
        "engineering": 156,
        "sales": 78,
        "marketing": 45,
        "support": 33
    }
}

Use Cases

• Market research and TAM analysis
• Lead generation planning
• Competitive intelligence
• Database coverage assessment

---

Technology Finder

Purpose: Discover the technology stack used by a website (6000+ technologies tracked).

Input Schema

Code
 
{
    "domain": "string (required)"
}

Parameters

Parameter	Type	Required	Description	Example
domain	string	Yes	Target domain name	"shopify.com"

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 11,
    "method": "tools/call",
    "params": {
        "name": "technology_finder",
        "arguments": {
            "domain": "shopify.com"
        }
    }
}

Response Format

Code
 
{
    "domain": "shopify.com",
    "technologies": [
        {
            "name": "Google Analytics",
            "category": "Analytics",
            "icon": "https://d12h6n0d1mbsct.cloudfront.net/technologies/google-analytics.png",
            "website": "https://analytics.google.com"
        },
        {
            "name": "Stripe",
            "category": "Payment Processing",
            "icon": "https://d12h6n0d1mbsct.cloudfront.net/technologies/stripe.png",
            "website": "https://stripe.com"
        },
        {
            "name": "Cloudflare",
            "category": "CDN",
            "icon": "https://d12h6n0d1mbsct.cloudfront.net/technologies/cloudflare.png",
            "website": "https://cloudflare.com"
        }
    ],
    "categories": {
        "Analytics": 3,
        "Payment Processing": 2,
        "CDN": 1,
        "Marketing Automation": 2,
        "CRM": 1
    }
}

Technology Categories

Common categories include:

• Analytics & Tracking
• Payment Processing
• CDN & Hosting
• Marketing Automation
• CRM & Sales
• E-commerce Platforms
• Email Services
• Customer Support
• Security & Compliance
• Development Tools

Use Cases

• Competitive analysis
• Sales intelligence (know what tools prospects use)
• Partnership opportunities
• Market research on technology adoption
• Lead qualification based on tech stack

---

Similar Finder

Purpose: Find companies similar to a target domain based on industry, size, and characteristics.

Input Schema

Code
 
{
    "domain": "string (required)",
    "limit": "number (optional, default: 10)"
}

Parameters

Parameter	Type	Required	Description	Example
domain	string	Yes	Target domain name	"salesforce.com"
limit	number	No	Max results (1-50)	20

Example Usage

Code
 
{
    "jsonrpc": "2.0",
    "id": 12,
    "method": "tools/call",
    "params": {
        "name": "similar_finder",
        "arguments": {
            "domain": "salesforce.com",
            "limit": 10
        }
    }
}

Response Format

Code
 
{
    "domain": "salesforce.com",
    "similar_domains": [
        {
            "domain": "hubspot.com",
            "similarity_score": 95,
            "industry": "CRM & Marketing Automation",
            "employees": "1001-5000",
            "website": "https://hubspot.com"
        },
        {
            "domain": "zoho.com",
            "similarity_score": 92,
            "industry": "CRM & Business Software",
            "employees": "5001-10000",
            "website": "https://zoho.com"
        },
        {
            "domain": "pipedrive.com",
            "similarity_score": 88,
            "industry": "Sales CRM",
            "employees": "501-1000",
            "website": "https://pipedrive.com"
        }
    ],
    "total": 47
}

Similarity Scoring

Similarity is calculated based on:

• Industry classification
• Company size (employees)
• Technology stack overlap
• Business model
• Target market

Score	Meaning
90-100	Very similar (direct competitors)
80-89	Highly similar (same space)
70-79	Similar (adjacent markets)
60-69	Somewhat similar
Below 60	Different but related

Use Cases

• Competitive intelligence
• TAM (Total Addressable Market) expansion
• Partnership opportunity discovery
• Market mapping
• Lead generation (find lookalike companies)

---

Companies Search

Purpose: Search for companies using natural language queries with advanced filters.

Input Schema

Code
 
{
    "query": "string (required)",
    "page": "number (optional, default: 1)",
    "limit": "number (optional, default: 50)",
    "filters": "object (optional)"
}

Parameters

Parameter	Type	Required	Description	Example
query	string	Yes	Natural language search	"SaaS companies in France"
page	number	No	Page number	1
limit	number	No	Results per page (max: 100)	50
filters	object	No	Advanced filter object	See filters below

Example Usage

Simple Natural Language Query:

Code
 
{
    "jsonrpc": "2.0",
    "id": 13,
    "method": "tools/call",
    "params": {
        "name": "companies_search",
        "arguments": {
            "query": "Real Estate companies in France",
            "limit": 50
        }
    }
}

Advanced Query with Filters:

Code
 
{
    "jsonrpc": "2.0",
    "id": 14,
    "method": "tools/call",
    "params": {
        "name": "companies_search",
        "arguments": {
            "query": "E-commerce companies",
            "limit": 50,
            "filters": {
                "country": ["US", "UK"],
                "employees": "51-200",
                "revenue": "$10M-$50M",
                "technologies": ["Shopify", "Stripe"]
            }
        }
    }
}

Response Format

Code
 
{
    "companies": [
        {
            "domain": "example-ecommerce.com",
            "organization": "Example E-commerce Inc",
            "industry": "E-commerce",
            "country": "US",
            "city": "San Francisco",
            "employees": "51-200",
            "revenue": "$10M-$50M",
            "founded": 2018,
            "description": "Leading online retailer for sustainable products",
            "technologies": ["Shopify", "Stripe", "Google Analytics"],
            "email_count": 67,
            "website": "https://example-ecommerce.com"
        }
    ],
    "total": 1247,
    "page": 1,
    "limit": 50,
    "has_more": true
}

Available Filters

Filter	Type	Description	Example
country	array[string]	Country codes (ISO 2-letter)	["US", "UK", "FR"]
industry	array[string]	Industry categories	["Technology", "Finance"]
employees	string	Employee range	"51-200"
revenue	string	Revenue range	"$10M-$50M"
founded	object	Year founded range	{"min": 2010, "max": 2020}
technologies	array[string]	Technologies used	["AWS", "Stripe"]
city	array[string]	City names	["San Francisco", "New York"]

Employee Ranges

• "1-10" - Micro
• "11-50" - Small
• "51-200" - Medium
• "201-500" - Large
• "501-1000" - Very Large
• "1001-5000" - Enterprise
• "5001+" - Mega Enterprise

Revenue Ranges

• "$0-$1M" - Bootstrapped
• "$1M-$10M" - Growing
• "$10M-$50M" - Established
• "$50M-$100M" - Large
• "$100M-$500M" - Very Large
• "$500M-$1B" - Major
• "$1B+" - Enterprise

Use Cases

• Lead generation with specific criteria
• Market research and analysis
• Competitive landscape mapping
• Partnership opportunity identification
• Investment research (VC/PE)
• Account-Based Marketing (ABM) list building

---

Common Parameters

Pagination

Many tools support pagination through limit and offset:

Code
 
{
    "limit": 25, // Items per page (max: 100)
    "offset": 50 // Items to skip (for page 3 with limit 25)
}

Confidence Scoring

Results include confidence scores (0-100):

• 90-100: Very High - Verified or highly likely
• 70-89: High - Strong indicators
• 50-69: Medium - Some evidence
• 30-49: Low - Weak indicators
• 0-29: Very Low - Speculative

Source Attribution

Many results include source information:

Code
 
{
    "sources": [
        {
            "uri": "https://example.com/page",
            "website_piece": "contact",
            "extracted_on": "2024-01-15",
            "last_seen_on": "2024-01-15",
            "still_on_page": true
        }
    ]
}

Error Handling

All tools return consistent error formats:

Code
 
{
    "content": [
        {
            "type": "text",
            "text": "Error: Invalid email format provided"
        }
    ],
    "isError": true
}

Common Error Types

• Invalid Input: Malformed parameters
• Rate Limit: API quota exceeded
• Authentication: Invalid API credentials
• Not Found: No results for query
• Network Error: Connection issues

Usage Tips

Best Practices

1. Start Small: Use small limits while testing
2. Verify Inputs: Validate parameters before sending
3. Handle Errors: Always check for error responses
4. Rate Limiting: Respect API limits and implement backoff
5. Data Quality: Use confidence scores for filtering

Performance Optimization

• Use pagination for large result sets
• Batch similar requests when possible
• Cache results when appropriate
• Monitor API quota usage

Data Privacy

• Only request necessary data
• Handle personal information securely
• Respect opt-out requests
• Follow local privacy regulations

---

Ready to use these tools? Check out the LLM Integration Guide for connecting with AI applications.