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 infotomba://domain/{domain}- Domain informationtomba://email/{email}- Email informationtomba://similar/{domain}- Similar domains analysistomba://technology/{domain}- Technology stack informationtomba://docs/api- API documentationtomba://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)5xxserver 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):```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`):```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:```bash
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-/SKILL.md`. Each one covers the tool's inputs, workflow, expected output, and an example call:
| Group | Skills |
| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Discovery | `tomba-domain-search`, `tomba-author-finder`, `tomba-linkedin-finder` |
| Phone | `tomba-phone-finder`, `tomba-phone-validator` |
| Enrichment | `tomba-person-enrichment`, `tomba-combined-enrichment` |
| Leads | `tomba-list-leads`, `tomba-create-lead` |
| Data quality | `tomba-list-flags`, `tomba-create-flag` |
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`:```bash
/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:```bash
codex mcp login tomba
To use API keys instead of OAuth, send the `X-Tomba-Key` and `X-Tomba-Secret` headers, or `Authorization: Bearer `, 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`):```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):```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:**```json
{
"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:```json
{
"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:```json
{
"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:```json
{
"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```bash
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:```bash
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```bash
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```bash
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:```bash
# 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```bash
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.```json
{
"name": "domain_search",
"arguments": {
"domain": "tomba.io",
"limit": 10,
"page": 1
}
}
Response:```json
{
"data": {
"organization": {
"website_url": "tomba.io",
"organization": "Tomba technology web service LLC",
"location": {
"country": "US",
"city": "Claymont",
"state": "Delaware",
"street_address": "1228 claymont",
"postal_code": "19703"
},
"social_links": {
"twitter_url": "https://twitter.com/tombaplatforum",
"facebook_url": "https://www.facebook.com/tombaplatforum",
"linkedin_url": "https://www.linkedin.com/company/tomba-io"
},
"disposable": false,
"webmail": false,
"phone_number": "(850) 790-5575",
"industries": "Information Technology and Services",
"founded": "2021",
"company_size": "1-10",
"company_type": "privately held",
"revenue": "$0-$1M",
"accept_all": false,
"description": "the most powerful email-finding tool which is able to list all the email addresses of people who are working in a particular company.",
"pattern": "{l}.{first}",
"total_similar": 35,
"keywords": [
"lead generation software"
],
"ranking": 661495,
"whois": {
"registrar_name": "namecheap, inc.",
"created_date": "2020-07-07T20:54:07+02:00",
"referral_url": "https://www.namecheap.com/"
},
"last_updated": "2025-09-06T00:22:01+02:00"
},
"emails": [
{
"email": "b.mohamed@tomba.io",
"first_name": "Mohamed",
"last_name": "Ben rebia",
"full_name": "Mohamed Ben rebia",
"gender": "male",
"phone_number": false,
"type": "personal",
"country": "DZ",
"position": "CEO",
"department": "executive",
"seniority": "senior",
"twitter": null,
"linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
"score": 100,
"verification": {
"date": "2025-09-22T00:00:00+02:00",
"status": "valid"
},
"sources": [
{
"uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
"website_url": "github.com",
"extracted_on": "2021-02-08T20:09:54+01:00",
"last_seen_on": "2021-02-08T22:43:40+01:00",
"still_on_page": true
},
....
]
},
...
...
...
...
...
]
},
"meta": {
"total": 21,
"pageSize": 10,
"current": 1,
"total_pages": 3,
"params": {
"domain": "tomba.io",
"page": 1,
"limit": 10,
"department": null,
"country": null,
"type": "all",
"live": false
}
}
}
### 2. Email Finder
Generate likely email addresses from domain, first name, and last name.```json
{
"name": "email_finder",
"arguments": {
"domain": "example.com",
"firstName": "John",
"lastName": "Doe"
}
}
Response:```json
{
"data": {
"email": "b.mohamed@tomba.io",
"first_name": "Mohamed",
"last_name": "Ben rebia",
"full_name": "Mohamed Ben rebia",
"website_url": "tomba.io",
"company": "Tomba technology web service LLC",
"position": "CEO",
"country": "DZ",
"gender": "male",
"twitter": null,
"linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
"score": 100,
"accept_all": null,
"phone_number": false,
"verification": {
"date": "2025-09-22T00:00:00+02:00",
"status": "valid"
},
"sources": [
{
"uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
"website_url": "github.com",
"extracted_on": "2021-02-08T20:09:54+01:00",
"last_seen_on": "2021-02-08T22:43:40+01:00",
"still_on_page": true
}
]
}
}
### 3. Email Verifier
Verify email address deliverability and check database presence.```json
{
"name": "email_verifier",
"arguments": {
"email": "b.mohamed@tomba.io"
}
}
Response:```json
{
"data": {
"email": {
"email": "b.mohamed@tomba.io",
"result": "deliverable",
"status": "valid",
"score": 99,
"smtp_provider": "Google Workspace",
"mx": {
"records": [
"aspmx.l.google.com",
"alt2.aspmx.l.google.com",
"alt1.aspmx.l.google.com",
"alt4.aspmx.l.google.com",
"alt3.aspmx.l.google.com"
]
},
"mx_check": true,
"smtp_server": true,
"smtp_check": true,
"accept_all": false,
"greylisted": false,
"block": true,
"gibberish": false,
"disposable": false,
"webmail": false,
"regex": true,
"whois": {
"registrar_name": "namecheap, inc.",
"referral_url": "https://www.namecheap.com/",
"created_date": "2020-07-07T20:54:07+02:00"
}
},
"sources": [
{
"uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
"website_url": "github.com",
"extracted_on": "2021-02-08T20:09:54+01:00",
"last_seen_on": "2021-02-08T22:43:40+01:00",
"still_on_page": true
}
]
}
}
### 4. Email Enrichment
Enrich an email address with additional contact information.```json
{
"name": "email_enrichment",
"arguments": {
"email": "b.mohamed@tomba.io"
}
}
Response:```json
{
"data": {
"email": "b.mohamed@tomba.io",
"first_name": "Mohamed",
"last_name": "Ben rebia",
"full_name": "Mohamed Ben rebia",
"website_url": "tomba.io",
"company": "Tomba technology web service LLC",
"position": "CEO",
"country": "DZ",
"gender": "male",
"twitter": null,
"linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
"score": 100,
"accept_all": null,
"phone_number": false,
"verification": {
"date": "2025-09-22T00:00:00+02:00",
"status": "valid"
},
"sources": [
{
"uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
"website_url": "github.com",
"extracted_on": "2021-02-08T20:09:54+01:00",
"last_seen_on": "2021-02-08T22:43:40+01:00",
"still_on_page": true
}
]
}
}
### 5. Author Finder
Find email addresses of article authors from a URL.```json
{
"name": "author_finder",
"arguments": {
"url": "https://example.com/article"
}
}
Response:```json
{
"data": {
"email": "b.mohamed@tomba.io",
"first_name": "Mohamed",
"last_name": "Ben rebia",
"full_name": "Mohamed Ben rebia",
"website_url": "tomba.io",
"company": "Tomba technology web service LLC",
"position": "CEO",
"country": "DZ",
"gender": "male",
"twitter": null,
"linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
"score": 100,
"accept_all": null,
"phone_number": false,
"verification": {
"date": "2025-09-22T00:00:00+02:00",
"status": "valid"
},
"sources": [
{
"uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
"website_url": "github.com",
"extracted_on": "2021-02-08T20:09:54+01:00",
"last_seen_on": "2021-02-08T22:43:40+01:00",
"still_on_page": true
}
]
}
}
### 6. LinkedIn Finder
Find email addresses from LinkedIn profile URLs.```json
{
"name": "linkedin_finder",
"arguments": {
"url": "https://linkedin.com/in/johndoe"
}
}
Response:```json
{
"data": {
"email": "b.mohamed@tomba.io",
"first_name": "Mohamed",
"last_name": "Ben rebia",
"full_name": "Mohamed Ben rebia",
"website_url": "tomba.io",
"company": "Tomba technology web service LLC",
"position": "CEO",
"country": "DZ",
"gender": "male",
"twitter": null,
"linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
"score": 100,
"accept_all": null,
"phone_number": false,
"verification": {
"date": "2025-09-22T00:00:00+02:00",
"status": "valid"
},
"sources": [
{
"uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
"website_url": "github.com",
"extracted_on": "2021-02-08T20:09:54+01:00",
"last_seen_on": "2021-02-08T22:43:40+01:00",
"still_on_page": true
}
]
}
}
### 7. Phone Finder
Search for phone numbers based on email, domain, or LinkedIn profile.```json
{
"name": "phone_finder",
"arguments": {
"domain": "tomba.io"
}
}
Response:```json
{
"data": {
"domain": "tomba.io",
"valid": true,
"local_format": "(850) 790-5575",
"intl_format": "+1 850-790-5575",
"e164_format": "+18507905575",
"rfc3966_format": "tel:+1-850-790-5575",
"country_code": "US",
"line_type": "FIXED_LINE_OR_MOBILE",
"carrier": "",
"timezones": ["America/New_York"]
}
}
### 8. Phone Validator
Validate phone numbers and check carrier information.```json
{
"name": "phone_validator",
"arguments": {
"phone": "+213667945402"
}
}
Response:```json
{
"data": {
"valid": true,
"local_format": "0667 94 54 02",
"intl_format": "+213 667 94 54 02",
"e164_format": "+213667945402",
"rfc3966_format": "tel:+213-667-94-54-02",
"country_code": "DZ",
"line_type": "MOBILE",
"carrier": "Mobilis",
"timezones": ["Europe/Paris"]
}
}
### 9. Email Count
Get the total number of email addresses for a domain.```json
{
"name": "email_count",
"arguments": {
…(正文过长,页面只展示前面部分,完整内容见仓库)
