Tomba MCP Server

1# [<img src="https://tomba.io/logo.svg" alt="Tomba" width="25"/>](https://tomba.io/) Tomba.io MCP Server
2 
3A 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.
4 
5## Features
6 
7### Tools (12 available)
8 
9- **[Domain Search](https://tomba.io/domain-search)**: Find all email addresses associated with a domain
10- **[Email Finder](https://tomba.io/email-finder)**: Generate likely email addresses from names and domains
11- **[Email Verifier](https://tomba.io/email-verifier)**: Verify email deliverability and check database presence
12- **[Email Enrichment](https://tomba.io/enrichment)**: Enrich emails with additional contact data
13- **[Author Finder](https://tomba.io/author-finder)**: Discover email addresses of article authors
14- **[LinkedIn Finder](https://tomba.io/linkedin-finder)**: Find emails from LinkedIn profile URLs
15- **[Phone Finder](https://tomba.io/phone-finder)**: Search phone numbers by email, domain, or LinkedIn
16- **[Phone Validator](https://tomba.io/phone-validator)**: Validate phone numbers and check carrier info
17- **[Email Count](https://tomba.io/email-count)**: Get total email counts for domains
18- **[Similar Finder](https://tomba.io/similar-domains)**: Find similar domains based on a target domain
19- **[Technology Finder](https://tomba.io/technology-finder)**: Discover technology stacks used by websites
20- **[Companies Search](https://app.tomba.io/reveal)**: Search for companies using natural language queries with advanced filters
21 
22### Resources (7 available)
23 
24- `tomba://api/status` - API status and account info
25- `tomba://domain/{domain}` - Domain information
26- `tomba://email/{email}` - Email information
27- `tomba://similar/{domain}` - Similar domains analysis
28- `tomba://technology/{domain}` - Technology stack information
29- `tomba://docs/api` - API documentation
30- `tomba://docs/tools` - Tools documentation
31 
32### Prompts (16 pre-built workflows)
33 
34- **find_contact** - Find complete contact info for a person
35- **verify_email_list** - Batch verify email addresses
36- **research_company** - Research company contacts and structure
37- **enrich_lead** - Enrich a lead with all available data
38- **find_journalists** - Find journalist contacts from articles
39- **finder_phone** - Find phone numbers for contacts
40- **validate_phone** - Validate a phone number
41- **competitor_analysis** - Analyze competitors using similar domains and technology
42- **technology_audit** - Comprehensive technology audit of a website
43- **domain_insights** - Get comprehensive insights about a domain including email count and technology
44- **bulk_domain_research** - Research multiple domains for email counts and basic information
45- **find_target_companies** - Find companies with advanced filters (size, type, revenue, industry)
46- **market_research** - Research companies in a market segment with comprehensive filtering
47- **lead_generation** - Generate leads by finding companies and their contacts
48- **prospect_enrichment** - Enrich company prospects with comprehensive data
49- **industry_analysis** - Analyze companies within an industry with detailed segmentation
50 
51#### Filter Options for Company Search Prompts
52 
53| Filter       | Available Values                                                                                                                                                     |
54| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
55| **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) |
56| **Type**     | education, government, nonprofit, private, public, personal                                                                                                          |
57| **Revenue**  | $0-$1M, $1M-$10M, $10M-$50M, $50M-$100M, $100M-$250M, $250M-$500M, $500M-$1B, $1B-$10B, $10B+                                                                        |
58| **Industry** | Based on LinkedIn Industry Codes V2 (140+ industries including Computer Software, Financial Services, Hospital & Health Care, etc.)                                  |
59 
60### Transport Options
61 
62- **stdio** - Standard input/output (default, for Claude Desktop)
63- **http** - HTTP server with REST endpoints
64 
65## Installation
66 
67### Prerequisites
68 
69- Node.js 18 or higher
70- npm or yarn
71- Tomba API account ([Sign up here](https://tomba.io))
72 
73## Screenshots
74 
75![Screenshot 1](assets/screenshots/screenshot1.png)
76![Screenshot 2](assets/screenshots/screenshot2.png)
77![Screenshot 3](assets/screenshots/screenshot3.png)
78![Screenshot 4](assets/screenshots/screenshot4.png)
79![Screenshot 5](assets/screenshots/screenshot5.png)
80 
81### Option 1: Install via NPX (Recommended)
82 
83The easiest way to use the Tomba MCP server is via npx, which doesn't require cloning the repository:
84 
85#### macOS/Linux
86 
87Add to your `claude_desktop_config.json` (`~/Library/Application Support/Claude/claude_desktop_config.json`):
88 
89```json
90{
91    "mcpServers": {
92        "tomba": {
93            "command": "npx",
94            "args": ["-y", "tomba-mcp-server"],
95            "env": {
96                "TOMBA_API_KEY": "your-api-key-here",
97                "TOMBA_SECRET_KEY": "your-secret-key-here"
98            }
99        }
100    }
101}
102```
103 
104#### Windows
105 
106Add to your `claude_desktop_config.json` (`%APPDATA%\Claude\claude_desktop_config.json`):
107 
108```json
109{
110    "mcpServers": {
111        "tomba": {
112            "command": "npx",
113            "args": ["-y", "tomba-mcp-server"],
114            "env": {
115                "TOMBA_API_KEY": "your-api-key-here",
116                "TOMBA_SECRET_KEY": "your-secret-key-here"
117            }
118        }
119    }
120}
121```
122 
123**Note:** The `-y` flag automatically accepts the installation prompt, and npx will always fetch the latest version.
124 
125### Option 2: Install from Source
126 
127If you want to modify the server or contribute to development:
128 
129```bash
130# Clone the repository
131git clone https://github.com/tomba-io/tomba-mcp-server.git
132cd tomba-mcp-server
133 
134# Install dependencies
135yarn install
136 
137# Build the project
138yarn build
139```
140 
141## Configuration
142 
143### Claude Desktop Setup
144 
145To use this server with Claude Desktop, add the configuration to your `claude_desktop_config.json` file.
146 
147#### Using NPX (Recommended)
148 
149This method automatically uses the latest published version:
150 
151**macOS/Linux** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
152 
153```json
154{
155    "mcpServers": {
156        "tomba": {
157            "command": "npx",
158            "args": ["-y", "tomba-mcp-server"],
159            "env": {
160                "TOMBA_API_KEY": "your-api-key-here",
161                "TOMBA_SECRET_KEY": "your-secret-key-here"
162            }
163        }
164    }
165}
166```
167 
168**Windows** (`%APPDATA%\Claude\claude_desktop_config.json`):
169 
170```json
171{
172    "mcpServers": {
173        "tomba": {
174            "command": "npx",
175            "args": ["-y", "tomba-mcp-server"],
176            "env": {
177                "TOMBA_API_KEY": "your-api-key-here",
178                "TOMBA_SECRET_KEY": "your-secret-key-here"
179            }
180        }
181    }
182}
183```
184 
185#### Using Local Installation
186 
187If you've built from source, use the absolute path to your installation:
188 
189**macOS/Linux:**
190 
191```json
192{
193    "mcpServers": {
194        "tomba": {
195            "command": "node",
196            "args": ["/ABSOLUTE/PATH/TO/tomba-mcp-server/server/index.js"],
197            "env": {
198                "TOMBA_API_KEY": "your-api-key-here",
199                "TOMBA_SECRET_KEY": "your-secret-key-here"
200            }
201        }
202    }
203}
204```
205 
206**Windows:**
207 
208```json
209{
210    "mcpServers": {
211        "tomba": {
212            "command": "node",
213            "args": [
214                "C:\\ABSOLUTE\\PATH\\TO\\tomba-mcp-server\\server\\index.js"
215            ],
216            "env": {
217                "TOMBA_API_KEY": "your-api-key-here",
218                "TOMBA_SECRET_KEY": "your-secret-key-here"
219            }
220        }
221    }
222}
223```
224 
225**Important Notes:**
226 
227- Replace `your-api-key-here` and `your-secret-key-here` with your actual Tomba API credentials
228- For local installation, replace `/ABSOLUTE/PATH/TO/tomba-mcp-server` with the full path to your installation directory
229- Restart Claude Desktop after updating the configuration
230 
231### Getting Tomba API Credentials
232 
2331. Visit [https://tomba.io](https://tomba.io)
2342. Sign up for an account or log in
2353. Navigate to your dashboard
2364. Go to API settings
2375. Copy your API Key and Secret Key
238 
239### Alternative: Using HTTP Transport
240 
241For HTTP transport with npx:
242 
243```json
244{
245    "mcpServers": {
246        "tomba": {
247            "command": "npx",
248            "args": [
249                "-y",
250                "tomba-mcp-server",
251                "--transport",
252                "http",
253                "--port",
254                "3000"
255            ],
256            "env": {
257                "TOMBA_API_KEY": "your-api-key-here",
258                "TOMBA_SECRET_KEY": "your-secret-key-here"
259            }
260        }
261    }
262}
263```
264 
265For HTTP transport with local installation:
266 
267```json
268{
269    "mcpServers": {
270        "tomba": {
271            "command": "node",
272            "args": [
273                "/ABSOLUTE/PATH/TO/tomba-mcp-server/server/index.js",
274                "--transport",
275                "http",
276                "--port",
277                "3000"
278            ],
279            "env": {
280                "TOMBA_API_KEY": "your-api-key-here",
281                "TOMBA_SECRET_KEY": "your-secret-key-here"
282            }
283        }
284    }
285}
286```
287 
288## Usage
289 
290### Command-line Options
291 
292```bash
293Usage: tomba-mcp-server [options]
294 
295Options:
296  --transport <type>    Transport type: 'stdio' or 'http' (default: stdio)
297  --port <number>       Port number for HTTP transport (default: 3000)
298  --help                Show help message
299 
300Environment Variables:
301  TOMBA_API_KEY         Your Tomba API key (required)
302  TOMBA_SECRET_KEY      Your Tomba secret key (required)
303 
304Examples:
305  # Run with stdio transport (default)
306  node server/index.js
307 
308  # Run with HTTP transport on default port (3000)
309  node server/index.js --transport http
310 
311  # Run with HTTP transport on custom port
312  node server/index.js --transport http --port 8080
313```
314 
315### Standalone HTTP Server
316 
317You can also run the server as a standalone HTTP service:
318 
319```bash
320export TOMBA_API_KEY="your-api-key"
321export TOMBA_SECRET_KEY="your-secret-key"
322node server/index.js --transport http --port 3000
323```
324 
325#### HTTP API Endpoints
326 
327- **POST /mcp** - Send JSON-RPC requests
328- **GET /mcp** - Server-Sent Events for notifications (requires X-Session-Id header)
329- **DELETE /mcp** - Terminate a session (requires X-Session-Id header)
330- **GET /health** - Health check endpoint
331- **GET /sessions** - List active sessions (requires authentication)
332 
333#### Example HTTP Request
334 
335```bash
336curl -X POST http://localhost:3000/mcp \
337  -H "Content-Type: application/json" \
338  -d '{
339    "jsonrpc": "2.0",
340    "method": "tools/call",
341    "params": {
342      "name": "email_finder",
343      "arguments": {
344        "domain": "stripe.com",
345        "firstName": "Patrick",
346        "lastName": "Collison"
347      }
348    },
349    "id": 1
350  }'
351```
352 
353## 🔧 Development
354 
355### Development Commands
356 
357```bash
358# Run in development mode
359yarn dev
360 
361# Build the project
362yarn build
363 
364# Run tests
365yarn test
366 
367# Run tests in watch mode
368yarn test:watch
369 
370# Run tests with coverage
371yarn test:coverage
372 
373# Lint code
374yarn lint
375 
376# Fix linting errors
377yarn lint:fix
378```
379 
380## 🔍 Debugging & Testing
381 
382### MCP Inspector (Recommended)
383 
384The easiest way to test and debug your MCP server:
385 
386```bash
387# Build and launch MCP Inspector
388yarn debug
389```
390 
391This opens a web interface where you can:
392 
393- 📋 View all available tools
394- 🧪 Test tools interactively
395- 📊 Inspect requests/responses
396- 🐛 Debug in real-time
397 
398### Alternative Debug Methods
399 
400```bash
401# Debug TypeScript directly
402yarn debug:dev
403 
404# Run integration tests
405yarn test:integration
406 
407# Manual testing
408yarn build
409echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | node server/index.js
410```
411 
412### VS Code Debugging
413 
414If using VS Code, use the included debug configurations:
415 
416- **Debug MCP Server**: Debug the compiled JavaScript
417- **Debug TypeScript**: Debug TypeScript source directly
418- **Debug with Inspector**: Debug with MCP Inspector
419- **Run Tests**: Debug Jest tests
420 
421See `DEBUG_GUIDE.md` for comprehensive debugging instructions.
422 
423## 🧪 Testing Individual Tools
424 
425### 1. Domain Search
426 
427Search for email addresses associated with a domain name.
428 
429```json
430{
431    "name": "domain_search",
432    "arguments": {
433        "domain": "tomba.io",
434        "limit": 10,
435        "page": 1
436    }
437}
438```
439 
440**Response:**
441 
442```json
443{
444  "data": {
445    "organization": {
446      "website_url": "tomba.io",
447      "organization": "Tomba technology web service LLC",
448      "location": {
449        "country": "US",
450        "city": "Claymont",
451        "state": "Delaware",
452        "street_address": "1228 claymont",
453        "postal_code": "19703"
454      },
455      "social_links": {
456        "twitter_url": "https://twitter.com/tombaplatforum",
457        "facebook_url": "https://www.facebook.com/tombaplatforum",
458        "linkedin_url": "https://www.linkedin.com/company/tomba-io"
459      },
460      "disposable": false,
461      "webmail": false,
462      "phone_number": "(850) 790-5575",
463      "industries": "Information Technology and Services",
464      "founded": "2021",
465      "company_size": "1-10",
466      "company_type": "privately held",
467      "revenue": "$0-$1M",
468      "accept_all": false,
469      "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.",
470      "pattern": "{l}.{first}",
471      "total_similar": 35,
472      "keywords": [
473        "lead generation software"
474      ],
475      "ranking": 661495,
476      "whois": {
477        "registrar_name": "namecheap, inc.",
478        "created_date": "2020-07-07T20:54:07+02:00",
479        "referral_url": "https://www.namecheap.com/"
480      },
481      "last_updated": "2025-09-06T00:22:01+02:00"
482    },
483    "emails": [
484      {
485        "email": "b.mohamed@tomba.io",
486        "first_name": "Mohamed",
487        "last_name": "Ben rebia",
488        "full_name": "Mohamed Ben rebia",
489        "gender": "male",
490        "phone_number": false,
491        "type": "personal",
492        "country": "DZ",
493        "position": "CEO",
494        "department": "executive",
495        "seniority": "senior",
496        "twitter": null,
497        "linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
498        "score": 100,
499        "verification": {
500          "date": "2025-09-22T00:00:00+02:00",
501          "status": "valid"
502        },
503        "sources": [
504          {
505            "uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
506            "website_url": "github.com",
507            "extracted_on": "2021-02-08T20:09:54+01:00",
508            "last_seen_on": "2021-02-08T22:43:40+01:00",
509            "still_on_page": true
510          },
511          ....
512        ]
513      },
514      ...
515      ...
516      ...
517      ...
518      ...
519    ]
520  },
521  "meta": {
522    "total": 21,
523    "pageSize": 10,
524    "current": 1,
525    "total_pages": 3,
526    "params": {
527      "domain": "tomba.io",
528      "page": 1,
529      "limit": 10,
530      "department": null,
531      "country": null,
532      "type": "all",
533      "live": false
534    }
535  }
536}
537```
538 
539### 2. Email Finder
540 
541Generate likely email addresses from domain, first name, and last name.
542 
543```json
544{
545    "name": "email_finder",
546    "arguments": {
547        "domain": "example.com",
548        "firstName": "John",
549        "lastName": "Doe"
550    }
551}
552```
553 
554**Response:**
555 
556```json
557{
558    "data": {
559        "email": "b.mohamed@tomba.io",
560        "first_name": "Mohamed",
561        "last_name": "Ben rebia",
562        "full_name": "Mohamed Ben rebia",
563        "website_url": "tomba.io",
564        "company": "Tomba technology web service LLC",
565        "position": "CEO",
566        "country": "DZ",
567        "gender": "male",
568        "twitter": null,
569        "linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
570        "score": 100,
571        "accept_all": null,
572        "phone_number": false,
573        "verification": {
574            "date": "2025-09-22T00:00:00+02:00",
575            "status": "valid"
576        },
577        "sources": [
578            {
579                "uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
580                "website_url": "github.com",
581                "extracted_on": "2021-02-08T20:09:54+01:00",
582                "last_seen_on": "2021-02-08T22:43:40+01:00",
583                "still_on_page": true
584            }
585        ]
586    }
587}
588```
589 
590### 3. Email Verifier
591 
592Verify email address deliverability and check database presence.
593 
594```json
595{
596    "name": "email_verifier",
597    "arguments": {
598        "email": "b.mohamed@tomba.io"
599    }
600}
601```
602 
603**Response:**
604 
605```json
606{
607    "data": {
608        "email": {
609            "email": "b.mohamed@tomba.io",
610            "result": "deliverable",
611            "status": "valid",
612            "score": 99,
613            "smtp_provider": "Google Workspace",
614            "mx": {
615                "records": [
616                    "aspmx.l.google.com",
617                    "alt2.aspmx.l.google.com",
618                    "alt1.aspmx.l.google.com",
619                    "alt4.aspmx.l.google.com",
620                    "alt3.aspmx.l.google.com"
621                ]
622            },
623            "mx_check": true,
624            "smtp_server": true,
625            "smtp_check": true,
626            "accept_all": false,
627            "greylisted": false,
628            "block": true,
629            "gibberish": false,
630            "disposable": false,
631            "webmail": false,
632            "regex": true,
633            "whois": {
634                "registrar_name": "namecheap, inc.",
635                "referral_url": "https://www.namecheap.com/",
636                "created_date": "2020-07-07T20:54:07+02:00"
637            }
638        },
639        "sources": [
640            {
641                "uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
642                "website_url": "github.com",
643                "extracted_on": "2021-02-08T20:09:54+01:00",
644                "last_seen_on": "2021-02-08T22:43:40+01:00",
645                "still_on_page": true
646            }
647        ]
648    }
649}
650```
651 
652### 4. Email Enrichment
653 
654Enrich an email address with additional contact information.
655 
656```json
657{
658    "name": "email_enrichment",
659    "arguments": {
660        "email": "b.mohamed@tomba.io"
661    }
662}
663```
664 
665**Response:**
666 
667```json
668{
669    "data": {
670        "email": "b.mohamed@tomba.io",
671        "first_name": "Mohamed",
672        "last_name": "Ben rebia",
673        "full_name": "Mohamed Ben rebia",
674        "website_url": "tomba.io",
675        "company": "Tomba technology web service LLC",
676        "position": "CEO",
677        "country": "DZ",
678        "gender": "male",
679        "twitter": null,
680        "linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
681        "score": 100,
682        "accept_all": null,
683        "phone_number": false,
684        "verification": {
685            "date": "2025-09-22T00:00:00+02:00",
686            "status": "valid"
687        },
688        "sources": [
689            {
690                "uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
691                "website_url": "github.com",
692                "extracted_on": "2021-02-08T20:09:54+01:00",
693                "last_seen_on": "2021-02-08T22:43:40+01:00",
694                "still_on_page": true
695            }
696        ]
697    }
698}
699```
700 
701### 5. Author Finder
702 
703Find email addresses of article authors from a URL.
704 
705```json
706{
707    "name": "author_finder",
708    "arguments": {
709        "url": "https://example.com/article"
710    }
711}
712```
713 
714**Response:**
715 
716```json
717{
718    "data": {
719        "email": "b.mohamed@tomba.io",
720        "first_name": "Mohamed",
721        "last_name": "Ben rebia",
722        "full_name": "Mohamed Ben rebia",
723        "website_url": "tomba.io",
724        "company": "Tomba technology web service LLC",
725        "position": "CEO",
726        "country": "DZ",
727        "gender": "male",
728        "twitter": null,
729        "linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
730        "score": 100,
731        "accept_all": null,
732        "phone_number": false,
733        "verification": {
734            "date": "2025-09-22T00:00:00+02:00",
735            "status": "valid"
736        },
737        "sources": [
738            {
739                "uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
740                "website_url": "github.com",
741                "extracted_on": "2021-02-08T20:09:54+01:00",
742                "last_seen_on": "2021-02-08T22:43:40+01:00",
743                "still_on_page": true
744            }
745        ]
746    }
747}
748```
749 
750### 6. LinkedIn Finder
751 
752Find email addresses from LinkedIn profile URLs.
753 
754```json
755{
756    "name": "linkedin_finder",
757    "arguments": {
758        "url": "https://linkedin.com/in/johndoe"
759    }
760}
761```
762 
763**Response:**
764 
765```json
766{
767    "data": {
768        "email": "b.mohamed@tomba.io",
769        "first_name": "Mohamed",
770        "last_name": "Ben rebia",
771        "full_name": "Mohamed Ben rebia",
772        "website_url": "tomba.io",
773        "company": "Tomba technology web service LLC",
774        "position": "CEO",
775        "country": "DZ",
776        "gender": "male",
777        "twitter": null,
778        "linkedin": "https://www.linkedin.com/in/mohamed-ben-rebia",
779        "score": 100,
780        "accept_all": null,
781        "phone_number": false,
782        "verification": {
783            "date": "2025-09-22T00:00:00+02:00",
784            "status": "valid"
785        },
786        "sources": [
787            {
788                "uri": "https://github.com/tomba-io/generic-emails/blob/084fc1a63d3cdaf9a34f255bedc2baea49a8e8b9/src/lib/validation/hash.ts",
789                "website_url": "github.com",
790                "extracted_on": "2021-02-08T20:09:54+01:00",
791                "last_seen_on": "2021-02-08T22:43:40+01:00",
792                "still_on_page": true
793            }
794        ]
795    }
796}
797```
798 
799### 7. Phone Finder
800 
801Search for phone numbers based on email, domain, or LinkedIn profile.
802 
803```json
804{
805    "name": "phone_finder",
806    "arguments": {
807        "domain": "tomba.io"
808    }
809}
810```
811 
812**Response:**
813 
814```json
815{
816    "data": {
817        "domain": "tomba.io",
818        "valid": true,
819        "local_format": "(850) 790-5575",
820        "intl_format": "+1 850-790-5575",
821        "e164_format": "+18507905575",
822        "rfc3966_format": "tel:+1-850-790-5575",
823        "country_code": "US",
824        "line_type": "FIXED_LINE_OR_MOBILE",
825        "carrier": "",
826        "timezones": ["America/New_York"]
827    }
828}
829```
830 
831### 8. Phone Validator
832 
833Validate phone numbers and check carrier information.
834 
835```json
836{
837    "name": "phone_validator",
838    "arguments": {
839        "phone": "+213667945402"
840    }
841}
842```
843 
844**Response:**
845 
846```json
847{
848    "data": {
849        "valid": true,
850        "local_format": "0667 94 54 02",
851        "intl_format": "+213 667 94 54 02",
852        "e164_format": "+213667945402",
853        "rfc3966_format": "tel:+213-667-94-54-02",
854        "country_code": "DZ",
855        "line_type": "MOBILE",
856        "carrier": "Mobilis",
857        "timezones": ["Europe/Paris"]
858    }
859}
860```
861 
862### 9. Email Count
863 
864Get the total number of email addresses for a domain.
865 
866```json
867{
868    "name": "email_count",
869    "arguments": {
870        "domain": "tomba.io"
871    }
872}
873```
874 
875**Response:**
876 
877```json
878{
879    "domain": "tomba.io",
880    "total": 245,
881    "personalEmails": 198,
882    "genericEmails": 47,
883    "department": {
884        "engineering": 45,
885        "sales": 38,
886        "marketing": 32,
887        "hr": 15,
888        "finance": 12,
889        "legal": 8,
890        "executive": 25,
891        "support": 28,
892        "other": 42
893    },
894    "seniority": {
895        "junior": 89,
896        "senior": 125,
897        "executive": 31
898    },
899    "source": "tomba_email_count"
900}
901```
902 
903### 10. Similar Finder
904 
905Find similar domains based on a specific domain.
906 
907```json
908{
909    "name": "similar_finder",
910    "arguments": {
911        "domain": "tomba.io"
912    }
913}
914```
915 
916**Response:**
917 
918```json
919{
920    "data": [
921        {
922            "website_url": "summit.com",
923            "name": "Summit",
924            "industries": "Wholesale"
925        },
926        {
927            "website_url": "hunter.io",
928            "name": "Hunter",
929            "industries": "Information Technology and Services"
930        },
931        {
932            "website_url": "voilaNorbert.com",
933            "name": "VoilaNorbert",
934            "industries": "Information Technology and Services"
935        }
936    ]
937}
938```
939 
940### 11. Technology Finder
941 
942Instantly reveal the technology stack of any website.
943 
944```json
945{
946    "name": "technology_finder",
947    "arguments": {
948        "domain": "tomba.io"
949    }
950}
951```
952 
953**Response:**
954 
955```json
956{
957    "domain": "tomba.io",
958    "data": [
959        {
960            "slug": "intercom",
961            "name": "Intercom",
962            "icon": "Intercom.png",
963            "website": "https://www.intercom.com",
964            "categories": {
965                "id": 10,
966                "slug": "analytics",
967                "name": "Analytics"
968            }
969        }
970    ]
971}
972```
973 
974### 12. Companies Search
975 
976Search for companies using natural language queries with advanced filters including location, industry, size, and revenue.
977 
978```json
979{
980    "name": "companies_search",
981    "arguments": {
982        "filters": {
983            "location_city": {
984                "include": ["san francisco"]
985            },
986            "industry": {
987                "include": ["technology"]
988            },
989            "size": {
990                "include": ["51-200", "201-500"]
991            }
992        },
993        "page": 1,
994        "limit": 10
995    }
996}
997```
998 
999**Response:**
1000 
1001```json
1002{
1003    "data": {
1004        "companies": [
1005            {
1006                "name": "Tech Company Inc",
1007                "domain": "techcompany.com",
1008                "industry": "Technology",
1009                "location": {
1010                    "city": "San Francisco",
1011                    "state": "California",
1012                    "country": "United States"
1013                },
1014                "size": "51-200",
1015                "revenue": "$10M-$50M"
1016            }
1017        ],
1018        "total": 150,
1019        "page": 1
1020    }
1021}
1022```
1023 
1024**Available Filters:**
1025 
1026- `location_city`: Filter by city with include/exclude arrays
1027- `location_state`: Filter by state with include/exclude arrays
1028- `location_country`: Filter by country with include/exclude arrays
1029- `industry`: Filter by industry (based on LinkedIn Industry Codes V2 - 140+ industries)
1030- `type`: Filter by company type: `education`, `government`, `nonprofit`, `private`, `public`, `personal`
1031- `size`: Filter by company size: `1-10`, `11-50`, `51-250`, `251-1K`, `1K-5K`, `5K-10K`, `10K-50K`, `50K-100K`, `100K+`
1032- `revenue`: Filter by revenue range: `$0-$1M`, `$1M-$10M`, `$10M-$50M`, `$50M-$100M`, `$100M-$250M`, `$250M-$500M`, `$500M-$1B`, `$1B-$10B`, `$10B+`
1033- `founded`: Filter by founding year with include/exclude arrays
1034- `keywords`: Filter by keywords with include/exclude arrays
1035- `sic`: Filter by SIC codes with include/exclude arrays
1036- `naics`: Filter by NAICS codes with include/exclude arrays
1037- `similar`: Filter by similar domains with include/exclude arrays
1038 
1039## Rate Limiting & Usage
1040 
1041### API Rate Limits
1042 
1043Tomba.io implements rate limiting based on your subscription plan:
1044 
1045- **Free Plan**: 50 requests per month
1046- **Growth Plan**: 5,000 requests per month + 10,000 verifications requests
1047- **Pro Plan**: 10,000 requests per month
1048- **Enterprise Plan**: 50,000 requests per month
1049- **Custom Plan**: Custom limits
1050 
1051Learn more about [Tomba Pricing Plans](https://tomba.io/pricing).
1052 
1053### Rate Limit Headers
1054 
1055Each API response includes rate limit information:
1056 
1057```
1058X-RateLimit-Limit: 1000
1059X-RateLimit-Remaining: 999
1060X-RateLimit-Reset: 1609459200
1061```
1062 
1063Learn more about [Tomba API Rate Limits](https://docs.tomba.io/rate-limits).
1064 
1065### Handling Rate Limits
1066 
1067When you exceed your rate limit, the API returns a `429 Too Many Requests` status with:
1068 
1069```json
1070{
1071    "error": {
1072        "type": "rate_limit",
1073        "message": "Rate limit exceeded. Please try again in 60 seconds",
1074        "code": 429
1075    }
1076}
1077```
1078 
1079### Best Practices
1080 
10811. **Monitor Usage**: Check your dashboard at [tomba.io/dashboard](https://app.tomba.io/dashboard)
10822. **Implement Backoff**: Handle 429 responses with exponential backoff
10833. **Batch Operations**: Use domain search for multiple emails from the same domain
10844. **Cache Results**: Store results locally to avoid duplicate requests
10855. **Plan Accordingly**: Upgrade your plan based on usage patterns
1086 
1087### Usage Tips
1088 
1089- Domain search returns multiple emails per request (more efficient than individual lookups)
1090- Email verification consumes credits only for valid email formats
1091- Phone finder may return multiple numbers per request
1092- Enrichment provides comprehensive data in a single request
1093 
1094## Troubleshooting
1095 
1096### Server Not Starting in Claude Desktop
1097 
10981. **Check Node.js version**: Ensure you have Node.js 18 or higher
1099 
1100    ```bash
1101    node --version
1102    ```
1103 
11042. **Using NPX:**
1105    - Ensure you have a stable internet connection for the first run
1106    - The `-y` flag should auto-accept the installation
1107    - NPX will cache the package after first use
1108 
11093. **Using Local Installation:**
1110    - Verify absolute path is correct in your config
1111    - Ensure `server/index.js` exists: `ls -la server/index.js`
1112    - Make sure you ran `yarn build` successfully
1113 
11144. **Verify API credentials**: Ensure your Tomba API keys are correct
1115 
11165. **Check Claude logs**:
1117    - macOS: `~/Library/Logs/Claude/mcp*.log`
1118    - Windows: `%APPDATA%\Claude\logs\mcp*.log`
1119 
1120### NPX-Specific Issues
1121 
1122**"npx command not found":**
1123 
1124- Ensure npm is installed: `npm --version`
1125- NPX comes with npm 5.2.0+, update if needed: `npm install -g npm`
1126 
1127**Package not found:**
1128 
1129- Verify the package is published: `npm view tomba-mcp-server`
1130- Try clearing npm cache: `npm cache clean --force`
1131 
1132**Always downloading package:**
1133 
1134- This is normal behavior with `-y` flag
1135- NPX caches the package after first download
1136- For a permanent installation, use local installation method
1137 
1138### Authentication Errors
1139 
1140- Verify your API keys at [https://app.tomba.io/dashboard](https://app.tomba.io/dashboard)
1141- Ensure environment variables are properly set in the config
1142- Check that your API subscription is active
1143 
1144### Tools Not Responding
1145 
1146- Check your Tomba API rate limits
1147- Verify network connectivity
1148- Review server logs for error messages
1149 
1150## About Tomba
1151 
1152Founded in 2020, Tomba prides itself on being the most reliable, accurate, and in-depth source of email address data available anywhere. We process terabytes of data to produce our Email finder API.
1153 
1154[![image](https://avatars.githubusercontent.com/u/67979591?s=200&v=4)](https://tomba.io/)
1155 
1156## Contributing
1157 
11581. Fork it (<https://github.com/tomba-io/tomba-mcp-server/fork>)
11592. Create your feature branch (`git checkout -b my-new-feature`)
11603. Commit your changes (`git commit -am 'Add some feature'`)
11614. Push to the branch (`git push origin my-new-feature`)
11625. Create a new Pull Request
1163 
1164## License
1165 
1166Please see the [License](LICENSE) file for more information.
1167 
1168## Support
1169 
1170- [GitHub Issues](https://github.com/tomba-io/tomba-mcp-server/issues)
1171- [Email Support](mailto:support@tomba.io)
1172- [Website](https://tomba.io)
1173