Skip to main content
Glama
Lusha MCP Server

Lusha MCP Server

Official
by lusha-oss

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

LUSHA_API_KEY

Your Lusha API key

-

✅

DISABLE_SSL

Disable SSL certificate verification (useful for development with self-signed certificates)

false

❌

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=true

Usage

Starting the Server

# Production
npm start

# Development with auto-reload
npm run dev

# Development with debug logging
npm run dev:debug

Available 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 URL

  • email: Email address

  • fullName + company information (companies array with name or domain)

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 request

  • At least one of: name, domain, fqdn, or companyId

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 successfully

Production (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 documentation

Contributing

  1. Fork the repository: https://github.com/lusha-oss/lusha-public-api-mcp/tree/master

  2. Create a feature branch

  3. Make your changes

  4. Add tests (when available)

  5. Run validation: npm run validate

  6. Submit 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 tools
companyBulkLookupA

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-filters

Inputs: 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

    A4.2/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct operation: company vs contact, and search/filter/enrich/bulk lookup are clearly separated. No overlapping purposes.

    Naming Consistency5/5

    All tool names follow a consistent camelCase pattern with entity prefix (company/contact/person) and action (BulkLookup, Enrich, Filters, Search). No mixing of conventions.

    Tool Count5/5

    Eight tools cover the full prospecting workflow (search, filter, enrich, bulk lookup) for both companies and contacts without being excessive or insufficient.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI assistants to find and enrich B2B contacts and companies with verified contact details and buying signals using Lusha's API.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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