Skip to main content
Glama
lusha-oss

Lusha MCP Server

Official
by lusha-oss
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lusha-oss/lusha-public-api-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server