Lusha MCP Server
OfficialClick on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Lusha MCP Server find the email and phone number for Satya Nadella at Microsoft"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Lusha MCP Server
A Model Context Protocol (MCP) server for integrating with the Lusha API. This server provides comprehensive person and company lookup capabilities with enterprise-grade error handling, logging, and configuration management.
Installation
For Claude Desktop
Add this server to your Claude Desktop configuration:
{
"mcpServers": {
"lusha": {
"command": "npx",
"args": ["@lusha-org/mcp@latest"],
"env": {
"LUSHA_API_KEY": "your_lusha_api_key_here"
}
}
}
}Related MCP server: Scrupp MCP server
Configuration
Environment Variables
Variable | Description | Default | Required |
| Your Lusha API key | - | ✅ |
| Disable SSL certificate verification (useful for development with self-signed certificates) |
| ❌ |
Example Configuration
# Required
LUSHA_API_KEY=your_actual_api_key_here
# Optional - Customize as needed
LOG_LEVEL=INFO
LUSHA_TIMEOUT=45000
# Development only - Skip SSL verification if needed
# DISABLE_SSL=trueUsage
Starting the Server
# Production
npm start
# Development with auto-reload
npm run dev
# Development with debug logging
npm run dev:debugAvailable MCP Tools
1. Person Bulk Lookup (personBulkLookup)
Find multiple people using various search criteria in a single request.
Parameters:
contacts: Array of contact objects (max 100)metadata(optional): Additional processing options
Contact Object Requirements: Each contact must have one of:
linkedinUrl: LinkedIn profile URLemail: Email addressfullName+ company information (companiesarray withnameordomain)
Example:
{
"contacts": [
{
"contactId": "contact_1",
"fullName": "John Doe",
"companies": [{"name": "Lusha", "isCurrent": true}]
},
{
"contactId": "contact_2",
"linkedinUrl": "https://linkedin.com/in/janedoe"
},
{
"contactId": "contact_3",
"email": "jane.smith@company.com"
}
],
"metadata": {
"revealEmails": true,
"revealPhones": false
}
}2. Company Bulk Lookup (companyBulkLookup)
Retrieve detailed information about multiple companies in a single request.
Parameters:
companies: Array of company objects (max 100)metadata(optional): Additional processing options
Company Object Requirements: Each company must have:
id: Unique identifier for the company in the requestAt least one of:
name,domain,fqdn, orcompanyId
Example:
{
"companies": [
{
"id": "company_1",
"domain": "lusha.com"
},
{
"id": "company_2",
"name": "Meta Platforms"
},
{
"id": "company_3",
"fqdn": "www.google.com"
}
]
}Response Format
All responses follow the MCP standard structure:
Success Response
{
"success": true,
"data": {
"contacts": { /* contact data by contactId */ },
"companies": { /* company data by companyId */ },
"requestId": "req_1234567890_abc123",
"timestamp": "2024-01-01T12:00:00.000Z"
},
"metadata": {
"toolName": "personBulkLookup",
"timestamp": "2024-01-01T12:00:00.000Z",
"version": "1.0.0"
}
}Error Response
{
"success": false,
"error": {
"message": "Invalid email format",
"status": 400,
"code": "VALIDATION_ERROR",
"category": "validation",
"severity": "medium",
"requestId": "req_1234567890_abc123",
"timestamp": "2024-01-01T12:00:00.000Z"
},
"metadata": {
"toolName": "personBulkLookup",
"timestamp": "2024-01-01T12:00:00.000Z",
"version": "1.0.0"
}
}Error Handling
The server implements comprehensive error handling with:
Error Categories
validation: Input validation errors
configuration: Configuration-related errors
api_client_error: 4xx HTTP errors from Lusha API
api_server_error: 5xx HTTP errors from Lusha API
rate_limit: Rate limiting errors
unknown: Unclassified errors
Error Severity Levels
low: Minor issues that don't affect functionality
medium: Issues that may affect some functionality
high: Significant issues that affect core functionality
critical: Critical issues that prevent operation
Logging
Log Levels
DEBUG: Detailed debugging information
INFO: General information about operations
WARN: Warning messages for potential issues
ERROR: Error messages for failed operations
FATAL: Critical errors that may cause the server to stop
Log Format
The enhanced logging system provides rich contextual information:
Development (Human-Readable):
[2025-05-26T11:37:40.962Z] INFO: Loading configuration from environment variables
[2025-05-26T11:37:40.962Z] INFO [environment=development, baseUrl=https://api.lusha.com, timeout=30000]: Configuration loaded successfully
[2025-05-26T11:37:40.962Z] INFO [serverName=lusha-mcp-server, serverVersion=1.0.0, environment=development]: Server starting up
[2025-05-26T11:37:40.963Z] INFO: Initializing MCP server transport...
[2025-05-26T11:37:40.964Z] INFO [serverName=lusha-mcp-server, serverVersion=1.0.0, availableTools=personBulkLookup,companyBulkLookup]: MCP server started successfullyProduction (Structured JSON):
{
"timestamp": "2024-01-01T12:00:00.000Z",
"level": 1,
"message": "Starting person bulk lookup request",
"context": {
"requestId": "req_1234567890_abc123",
"toolName": "personBulkLookup",
"operation": "bulk_person_lookup"
},
"metadata": {
"inputParams": {
"contactCount": 3
}
}
}Development
Project Structure
src/
├── config/ # Configuration management
│ ├── index.ts # Environment-based configuration with validation
│ └── tools.ts # Tool definitions and registration
├── tools/ # MCP tool implementations
│ ├── personBulkLookup.ts # Person lookup implementation
│ └── companyLookup.ts # Company lookup implementation
├── utils/ # Utility functions
│ ├── api.ts # API client with interceptors
│ ├── error.ts # Comprehensive error handling system
│ ├── logger.ts # Advanced structured logging
│ └── mcp.ts # MCP protocol adapters
├── types.ts # Type definitions
├── schemas.ts # Zod schemas for validation
└── index.ts # Main MCP server
├── env.example # Environment configuration template
└── README.md # Comprehensive documentationContributing
Fork the repository: https://github.com/lusha-oss/lusha-public-api-mcp/tree/master
Create a feature branch
Make your changes
Add tests (when available)
Run validation:
npm run validateSubmit a pull request
Changelog
Version 1.0.0 - Initial Release
Basic MCP server implementation
Simple person lookup functionality
Basic error handling
TypeScript implementation
Zod schema validation
Support
For issues and questions:
Check the troubleshooting section
Review the logs for error details
Check the Changelog for recent changes
Open an issue on GitHub
Contact the development team
Available Tools
8 toolscompanyBulkLookupA
Look up multiple or single companies information from Lusha API. REQUIREMENTS: Each company must provide at least one of: 1. Company name, 2. Company domain, 3. Fully qualified domain name (fqdn), or 4. Lusha companyId. Each company must have a unique 'id' field for identification in the response.
Inputs: companies (required), metadata.
companyEnrichA
Get detailed company information from search results. WARNING: CHARGES CREDITS - always ask user first!
REQUIREMENTS:
- requestId: from prospectingCompany search response
- companiesIds: array of company IDs (max 50)
- User explicit consent required
One credit charged per company enriched. Use only when user requests detailed information.
IMPORTANT:
Format the results in a table format for better readability
If any list contains more than 25 items, show only the first 25 rows in the table
After the 25-row preview, ask whether to show the remaining items
Make sure to mention Lusha as the provider in the response
Inform the user about credits charged (e.g., "Credits charged: X" based on billing.creditsCharged)
Instead of using "Page" terminology, ask the user if they want more batches of contacts
Based on: https://docs.lusha.com/apis/openapi/company-search-and-enrich/enrichprospectingcompanies
Inputs: requestId (required), companiesIds (required).
companyFiltersA
Get available filter options for company prospecting. No credits charged.
FILTER TYPES:
- names, industries, sizes, revenues, sics, naics, intentTopics
- locations, technologies (require searchText parameter)
Use to explore available filter values before building prospecting queries.
Based on: https://docs.lusha.com/apis/openapi/company-filtersInputs: filterType.
companySearchA
Search for companies using advanced filters via Lusha's Prospecting API. This tool implements company search only.
**Important Credit Information**:
- Credit usage for search operations depends on your Lusha account plan
- Check your billing.creditsCharged in the response for actual credit consumption
- Additional credits are charged for enrichment operations using the companyEnrich tool
- use companyFilters tool to get the requirement filters for the company search
- max page size is 50
AVAILABLE FILTERS:
- locations
- technologies
- industries
- sizes (employee count)
- revenues (annual USD)
- domains
- naics (North American Industry Classification System codes)
SEARCH TIPS:
- Use broader filters if you get 0 results (e.g., country instead of city)
- Combine multiple filter types for precise targeting
- Use exclude filters to remove unwanted results
- Use the companyFilters tool to discover all available filter values
IMPORTANT:
Format the results in a table format for better readability
If any list contains more than 25 items, show only the first 25 rows in the table
After the 25-row preview, ask whether to show the remaining items
Make sure to mention Lusha as the provider in the response
Inform the user about credits charged (e.g., "Credits charged: X" based on billing.creditsCharged)
Instead of using "Page" terminology, ask the user if they want more batches of contacts
Based on: https://docs.lusha.com/apis/openapi/company-search-and-enrich/searchprospectingcompanies
Inputs: filters (required), pages.
contactEnrichA
Enrich contacts from search results. This is step 3 of the prospecting process. IMPORTANT: - The requestId parameter MUST be the exact UUID received from the contactSearch response - ALWAYS ask the user which specific contacts they want to enrich before proceeding - revealEmails and revealPhones parameters are only available to customers on the Unified Credits pricing plan - Attempting to use these parameters on other plans will result in a 403 Unauthorized error - When neither parameter is used, the API returns both email addresses and phone numbers if available - IMPORTANT:
Format the results in a table format for better readability
If any list contains more than 25 items, show only the first 25 rows in the table
After the 25-row preview, ask whether to show the remaining items
Make sure to mention Lusha as the provider in the response
Inform the user about credits charged (e.g., "Credits charged: X" based on billing.creditsCharged)
Instead of using "Page" terminology, ask the user if they want more batches of contacts
Inputs: requestId (required), contactIds (required), revealEmails, revealPhones.
contactFiltersA
Get available filter values for contact search. Supports: 1. departments - List of available departments 2. seniority - List of available seniority levels 3. existing_data_points - List of available data points 4. all_countries - List of available countries 5. locations - Search for locations by text (requires locationSearchText parameter)
Inputs: filterType (required), locationSearchText.
contactSearchA
Search for contacts using various filters in Lusha API. This is step 2 of the prospecting process. IMPORTANT: - After returning search results, ALWAYS ask the user if they want to enrich specific contacts - MCP sets page size to 25 by default (API's default is 20 if not specified) - Page/offset index starts from 0 - always use contactFilters tool to get the requirement filters for the contact search" - IMPORTANT:
Format the results in a table format for better readability
If any list contains more than 25 items, show only the first 25 rows in the table
After the 25-row preview, ask whether to show the remaining items
Make sure to mention Lusha as the provider in the response
Inform the user about credits charged (e.g., "Credits charged: X" based on billing.creditsCharged)
Instead of using "Page" terminology, ask the user if they want more batches of contacts
The search supports filtering by: 1. Contact properties: - departments - seniority - existing data points - countries - locations 2. Company properties: - names (company names) - locations (company headquarters) - technologies (tech stack used) - mainIndustriesIds (main industry sectors) - subIndustriesIds (sub-industry categories) - intentTopics (company intent signals) - sizes (employee count ranges) - revenues (revenue ranges) - sics (Standard Industrial Classification codes) - naics (North American Industry Classification System codes) Pagination is supported through either 'pages' or 'offset' parameters.
Inputs: filters (required), pages, offset.
personBulkLookupA
Look up multiple or single persons information from Lusha API. REQUIREMENTS: Each person body must have a combination of: 1. LinkedIn URL, 2. full name + company domain/name, or 3. email address. IMPORTANT: Only use revealEmails or revealPhones parameters when specifically requested by the user for email-only or phone-only results.
Inputs: contacts (required), metadata.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct operation: company vs contact, and search/filter/enrich/bulk lookup are clearly separated. No overlapping purposes.
All tool names follow a consistent camelCase pattern with entity prefix (company/contact/person) and action (BulkLookup, Enrich, Filters, Search). No mixing of conventions.
Eight tools cover the full prospecting workflow (search, filter, enrich, bulk lookup) for both companies and contacts without being excessive or insufficient.
The tool set provides a complete lifecycle for company and contact data access: search with filters, enrichment, and bulk lookup. No obvious gaps for the intended purpose.
Maintenance
Related MCP Connectors
Search companies, enrich contacts, and reveal emails and phones from your AI agent.
Give AI agents the LinkedIn tools to find, qualify, engage, and follow up with prospects.
Web search, scraping, crawling, research, a browser agent, and company and people data.
Real-time B2B data for agents: search and enrich 1B+ people and 200M+ company profiles.
Related MCP Servers
AlicenseNot gradedqualityCmaintenanceEnables AI assistants to find and enrich B2B contacts and companies with verified contact details and buying signals using Lusha's API.4MIT
Scrupp MCP serverofficial
AlicenseAqualityBmaintenanceExport LinkedIn, Sales Navigator and Apollo searches, find decision makers, and find and verify work emails from any MCP client.1061 npmMIT- AlicenseNot gradedqualityCmaintenanceEnables AI agents to search a global professional database in plain English, reveal full profiles, and fetch verified work emails, email verification, reverse email lookup, and LinkedIn and company lookups. Searches are free, while most lookups cost credits that are refunded automatically when nothing is found.MIT
- AlicenseNot gradedqualityCmaintenanceEnables agents to search and enrich B2B companies and people, find verified work emails and US phone numbers, search job postings, and consult live documentation, exposing one tool per API endpoint.1MIT