Lusha MCP Server

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.

Unlock Lusha's contact enrichment power directly within your AI agents.

This Model Context Protocol (MCP) server provides a seamless bridge to the Lusha API, enabling tools like Claude Desktop, Cursor, or other MCP-compatible clients to perform business contact and company lookups effortlessly.

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"
      }
    }
  }
}

Configuration

Environment Variables

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

• **DE