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

• 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