Tomba.io MCP Server

A Model Context Protocol (MCP) server for integrating with the Tomba.io API. This server provides comprehensive email discovery, verification, and enrichment capabilities through a standardized MCP interface.

Features

Tools (28 available)

Email Discovery

• Domain Search: Find all email addresses associated with a domain
• Email Finder: Generate likely email addresses from names and domains
• Author Finder: Discover email addresses of article authors
• LinkedIn Finder: Find emails from LinkedIn profile URLs
• Email Count: Get total email counts for domains
• Email Sources: Find where an email address was found on the web
• Email Format: Get the email format patterns used by a domain

Verification

• Email Verifier: Verify email deliverability and check database presence

Enrichment

• Email Enrichment: Enrich emails with additional contact data
• Person Enrichment: Find person data by email (name, position, social profiles)
• Company Enrichment: Find company data by domain (industry, size, location)
• Combined Enrichment: Combined person + company enrichment by email

Phone

• Phone Finder: Search phone numbers by email, domain, or LinkedIn
• Phone Validator: Validate phone numbers and check carrier info

Domain Intelligence

• Domain Status: Check if a domain is webmail or disposable
• Autocomplete: Company name suggestions with logo and domain info
• Similar Finder: Find similar domains based on a target domain
• Technology Finder: Discover technology stacks used by websites
• Location: Get employees location count by country

Company Search

• Companies Search: Search for companies using natural language queries with advanced filters

Account & Management

• Account Info: Get current account information, plan, and credits
• Usage Info: Get API usage statistics across all endpoints
• List Flags: List submitted data flags with status and credit refunds
• Create Flag: Report incorrect data (hard bounces, invalid emails) for credit recovery
• List Leads: List leads with optional domain filter
• Create Lead: Add a new lead to a list
• List Keys: List API keys
• Get Logs: Get recent API request logs

Resources (7 available)

• tomba://api/status - API status and account info
• tomba://domain/{domain} - Domain information
• tomba://email/{email} - Email information
• tomba://similar/{domain} - Similar domains analysis
• tomba://technology/{domain} - Technology stack information
• tomba://docs/api - API documentation
• tomba://docs/tools - Tools documentation

Prompts (16 pre-built workflows)

• find_contact - Find complete contact info for a person
• verify_email_list - Batch verify email addresses
• research_company - Research company contacts and structure
• enrich_lead - Enrich a lead with all available data
• find_journalists - Find journalist contacts from articles
• phone_finder - Find phone numbers for contacts
• validate_phone - Validate a phone number
• competitor_analysis - Analyze competitors using similar domains and technology
• technology_audit - Comprehensive technology audit of a website
• 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
• find_target_companies - Find companies with advanced filters (size, type, revenue, industry)
• market_research - Research companies in a market segment with comprehensive filtering
• lead_generation - Generate leads by finding companies and their contacts
• prospect_enrichment - Enrich company prospects with comprehensive data
• industry_analysis - Analyze companies within an industry with detailed segmentation

Filter Options for Company Search Prompts

Filter	Available Values
Size	1-10 (Micro), 11-50 (Small), 51-250 (Mid-sized), 251-1K (Medium-large), 1K-5K (Large), 5K-10K (Very large), 10K-50K (Enterprise), 50K-100K (Massive), 100K+ (Global)
Type	education, government, nonprofit, private, public, personal
Revenue	$0-$1M, $1M-$10M, $10M-$50M, $50M-$100M, $100M-$250M, $250M-$500M, $500M-$1B, $1B-$10B, $10B+
Industry	Based on LinkedIn Industry Codes V2 (140+ industries including Computer Software, Financial Services, Hospital & Health Care, etc.)

Performance & Reliability

Timeout

All API calls have a 120-second timeout. Tomba searches run in real time against live infrastructure — response times vary with the target company's SMTP server speed, website responsiveness, and the depth of catch-all detection.

Retry with Exponential Backoff

All API calls automatically retry up to 3 times with exponential backoff on:

• 429 Too Many Requests (rate limit exceeded)
• 5xx server errors

Retry delays: 1s → 2s → 4s.

Rate Limits

Rate limits are enforced per endpoint and per plan:

Plan	Per Second	Per Minute	Per Day
Free	1	2	5
Basic	3	50	500
Growth	5	80	1,000
Pro	8	150	4,000
50,000+ plans	Unlimited	Unlimited	Unlimited

No credits are charged when Tomba cannot provide a result. Duplicate requests within 30 days are not counted again.

Transport Options

• stdio - Standard input/output (default, for Claude Desktop)
• http - HTTP server with REST endpoints

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Tomba API account (Sign up here)

Screenshots

Note: The npm package has been renamed from tomba-mcp-server to @tomba-io/tomba-mcp-server. Please update your configurations accordingly.

Option 1: Install via NPX (Recommended)

The easiest way to use the Tomba MCP server is via npx, which doesn't require cloning the repository:

macOS/Linux

Add to your claude_desktop_config.json (~/Library/Application Support/Claude/claude_desktop_config.json):

{
    "mcpServers": {
        "tomba": {
            "command": "npx",
            "args": ["-y", "@tomba-io/tomba-mcp-server"],
            "env": {
                "TOMBA_API_KEY": "your-api-key-here",
                "TOMBA_SECRET_KEY": "your-secret-key-here"
            }
        }
    }
}

Windows

Add to your claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json):

{
    "mcpServers": {
        "tomba": {
            "command": "npx",
            "args": ["-y", "@tomba-io/tomba-mcp-server"],
            "env": {
                "TOMBA_API_KEY": "your-api-key-here",
                "TOMBA_SECRET_KEY": "your-secret-key-here"
            }
        }
    }
}

Note: The -y flag automatically accepts the installation prompt, and npx will always fetch the latest version.

Option 2: Install from Source

If you want to modify the server or contribute to development:

# Clone the repository
git clone https://github.com/tomba-io/tomba-mcp-server.git
cd tomba-mcp-server

# Install dependencies
yarn install

# Build the project
yarn build

Configuration

OpenClaw Skill

This repository includes workspace-local skills in skills/. The Cursor plugin (.cursor-plugin/plugin.json) loads them as well.

skills/tomba-contact-intelligence/SKILL.md is the main skill. It helps the agent pick the right Tomba MCP tools for contact discovery, company research, email verification, phone lookup, and prospect enrichment workflows.

Each MCP tool also has its own skill folder, skills/tomba-<tool-name>/SKILL.md. Each one covers the tool's inputs, workflow, expected output, and an example call:

Group	Skills
Email	tomba-email-finder, tomba-email-verifier, tomba-email-enrichment, tomba-email-count, tomba-email-sources, tomba-email-format
Discovery	tomba-domain-search, tomba-author-finder, tomba-linkedin-finder
Phone	tomba-phone-finder, tomba-phone-validator
Company	tomba-companies-search, tomba-company-enrichment, tomba-similar-finder, tomba-technology-finder, tomba-autocomplete, tomba-location, tomba-domain-status
Enrichment	tomba-person-enrichment, tomba-combined-enrichment
Leads	tomba-list-leads, tomba-create-lead
Data quality	tomba-list-flags, tomba-create-flag
Account	tomba-account-info, tomba-usage-info, tomba-list-keys, tomba-get-logs

To use it:

1. Open this repository as your OpenClaw workspace, or copy the skills/tomba-* directories you need into your OpenClaw skills directory.
2. Ensure the Tomba MCP server is configured and available to OpenClaw.
3. Start a new OpenClaw session so the skill is loaded.

Example prompts:

• "Find the best contact for partnerships at stripe.com and verify the email before you return it."
• "Research fintech companies in Germany, then identify likely sales contacts for the top matches."
• "Enrich this prospect with email, phone, company technology, and similar competitors: jane@acme.com"

Claude Code Plugin

This repository is also a Claude Code plugin marketplace (.claude-plugin/). The plugin bundles every skill in skills/ and connects to the hosted MCP server at https://mcp.tomba.io/mcp:

/plugin marketplace add tomba-io/tomba-mcp-server
/plugin install tomba@tomba

Then run /mcp and authenticate the tomba server with OAuth. No API keys are needed. Plugin skills are namespaced, for example /tomba:tomba-domain-search zapier.com.

Codex Plugin

.codex-plugin/plugin.json packages the same skills for OpenAI Codex. It loads the remote server from .mcp.json. After installing the plugin, sign in with OAuth:

codex mcp login tomba

To use API keys instead of OAuth, send the X-Tomba-Key and X-Tomba-Secret headers, or Authorization: Bearer <base64(ta_key:ts_secret)>, to https://mcp.tomba.io/mcp.

Claude Desktop Setup

To use this server with Claude Desktop, add the configuration to your claude_desktop_config.json file.

Using NPX (Recommended)

This method automatically uses the latest published version:

macOS/Linux (~/Library/Application Support/Claude/claude_desktop_config.json):

{
    "mcpServers": {
        "tomba": {
            "command": "npx",
            "args": ["-y", "@tomba-io/tomba-mcp-server"],
            "env": {
                "TOMBA_API_KEY": "your-api-key-here",
                "TOMBA_SECRET_KEY": "your-secret-key-here"
            }
        }
    }
}

Windows (%APPDATA%\Claude\claude_desktop_config.json):

{
    "mcpServers": {
        "tomba": {
            "command": "npx",
            "args": ["-y", "@tomba-io/tomba-mcp-server"],
            "env": {
                "TOMBA_API_KEY": "your-api-key-here",
                "TOMBA_SECRET_KEY": "your-secret-key-here"
            }
        }
    }
}

Using Local Installation

If you've built from source, use the absolute path to your installation:

macOS/Linux:

{
    "mcpServers": {
        "tomba": {
            "command": "node",
            "args": ["/ABSOLUTE/PATH/TO/tomba-mcp-server/server/index.js"],
            "env": {
                "TOMBA_API_KEY": "your-api-key-here",
                "TOMBA_SECRET_KEY": "your-secret-key-here"
            }
        }
    }
}

Windows:

{
    "mcpServers": {
        "tomba": {
            "command": "node",
            "args": [
                "C:\\ABSOLUTE\\PATH\\TO\\tomba-mcp-server\\server\\index.js"
            ],
            "env": {
                "TOMBA_API_KEY": "your-api-key-here",
                "TOMBA_SECRET_KEY": "your-secret-key-here"
            }
        }
    }
}

Important Notes:

• Replace your-api-key-here and your-secret-key-here with your actual Tomba API credentials
• For local installation, replace /ABSOLUTE/PATH/TO/tomba-mcp-server with the full path to your installation directory
• Restart Claude Desktop after updating the configuration

Getting Tomba API Credentials

1. Visit https://tomba.io
2. Sign up for an account or log in
3. Navigate to your dashboard
4. Go to API settings
5. Copy your API Key and Secret Key

Alternative: Using HTTP Transport

For HTTP transport with npx:

{
    "mcpServers": {
        "tomba": {
            "command": "npx",
            "args": [
                "-y",
                "@tomba-io/tomba-mcp-server",
                "--transport",
                "http",
                "--port",
                "3000"
            ],
            "env": {
                "TOMBA_API_KEY": "your-api-key-here",
                "TOMBA_SECRET_KEY": "your-secret-key-here"
            }
        }
    }
}

For HTTP transport with local installation:

{
    "mcpServers": {
        "tomba": {
            "command": "node",
            "args": [
                "/ABSOLUTE/PATH/TO/tomba-mcp-server/server/index.js",
                "--transport",
                "http",
                "--port",
                "3000"
            ],
            "env": {
                "TOMBA_API_KEY": "your-api-key-here",
                "TOMBA_SECRET_KEY": "your-secret-key-here"
            }
        }
    }
}

Usage

Command-line Options

Usage: tomba-mcp-server [options]

Options:
  --transport <type>    Transport type: 'stdio' or 'http' (default: stdio)
  --port <number>       Port number for HTTP transport (default: 3000)
  --help                Show help message

Environment Variables:
  TOMBA_API_KEY         Your Tomba API key (required)
  TOMBA_SECRET_KEY      Your Tomba secret key (required)

Examples:
  # Run with stdio transport (default)
  node server/index.js

  # Run with HTTP transport on default port (3000)
  node server/index.js --transport http

  # Run with HTTP transport on custom port
  node server/index.js --transport http --port 8080

Standalone HTTP Server

You can also run the server as a standalone HTTP service:

export TOMBA_API_KEY="your-api-key"
export TOMBA_SECRET_KEY="your-secret-key"
node server/index.js --transport http --port 3000

HTTP API Endpoints

• POST /mcp - Send JSON-RPC requests
• GET /mcp - Server-Sent Events for notifications (requires X-Session-Id header)
• DELETE /mcp - Terminate a session (requires X-Session-Id header)
• GET /health - Health check endpoint
• GET /sessions - List active sessions (requires authentication)

Example HTTP Request

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "email_finder",
      "arguments": {
        "domain": "stripe.com",
        "firstName": "Patrick",
        "lastName": "Collison"
      }
    },
    "id": 1
  }'

🔧 Development

Development Commands

# Run in development mode
yarn dev

# Build the project
yarn build

# Run tests
yarn test

# Run tests in watch mode
yarn test:watch

# Run tests with coverage
yarn test:coverage

# Lint code
yarn lint

# Fix linting errors
yarn lint:fix

🔍 Debugging & Testing

MCP Inspector (Recommended)

The easiest way to test and debug your MCP server:

# Build and launch MCP Inspector
yarn debug

This opens a web interface where you can:

• 📋 View all available tools
• 🧪 Test tools interactively
• 📊 Inspect requests/responses
• 🐛 Debug in real-time

Alternative Debug Methods

# Debug TypeScript directly
yarn debug:dev

# Run integration tests
yarn test:integration

# Manual testing
yarn build
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node server/index.js

VS Code Debugging

If using VS Code, use the included debug configurations:

• Debug MCP Server: Debug the compiled JavaScript
• Debug TypeScript: Debug TypeScript source directly
• Debug with Inspector: Debug with MCP Inspector
• Run Tests: Debug Jest tests

See DEBUG_GUIDE.md for comprehensive debugging instructions.

🧪 Testing Individual Tools

1. Domain Search

Search for email addresses associated with a domain name.

{
    "name": "domain_search",
    "arguments": {
        "domain": "tomba.io",
        "limit": 10,
        "page": 1
    }
}

Response: