# Lusha MCP Server

The Lusha MCP Server connects Lusha's B2B contact and company data directly to your AI workflows. Use it to find, enrich, and prospect through natural language - no manual API calls required.

## Connection Methods

Lusha MCP supports two authentication methods. Which one you use depends on your client:

| Method | Description | Supported clients |
|  --- | --- | --- |
| **OAuth** | One-click authentication via Lusha's official connector | Claude, ChatGPT |
| **API Key** | Pass your Lusha API key via the `x-api-key` request header | VS Code, Cursor, n8n, Gemini CLI, and any other client |


## Client Setup

### OAuth Clients

#### Claude

Connect via Lusha's official listing in the Claude connector directory.

1. Go to [claude.ai/directory/connectors/lusha](https://claude.ai/directory/connectors/lusha)
2. Click **Add to Claude**
3. Complete OAuth authentication
4. Open any chat, click the tools menu, and confirm Lusha tools are listed


#### ChatGPT

Connect via Lusha's official listing in the ChatGPT app directory.

1. Go to [chatgpt.com/apps?q=lusha](https://chatgpt.com/apps?q=lusha)
2. Click **Connect**
3. Complete OAuth authentication
4. Open any chat, click the tools menu, and confirm Lusha tools are listed


### Custom MCP

For clients not listed above, connect using your Lusha API key.

**Get your API key:** Sign in to Lusha and go to [API → Manage API Keys](https://dashboard.lusha.com/api/manage-api-keys).

**MCP Server URL:** `https://mcp.lusha.com`

#### VS Code (GitHub Copilot)

Requires VS Code 1.99 or higher.

**Option A: Settings UI**

1. Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Run **MCP: Add Server**
3. Select **HTTP**, enter `https://mcp.lusha.com`, and name it `lusha`
4. Add `x-api-key` as the header name and your API key as the value when prompted


**Option B: `settings.json`**


```json
{
  "mcp": {
    "servers": {
      "lusha": {
        "type": "http",
        "url": "https://mcp.lusha.com",
        "headers": {
          "x-api-key": "YOUR_LUSHA_API_KEY"
        }
      }
    }
  }
}
```

To use Lusha tools, open **GitHub Copilot Chat**, switch to **Agent mode**, and enable Lusha from the **Tools** menu.

#### Cursor

1. Open (or create) your Cursor MCP config:
  - **macOS/Linux:** `~/.cursor/mcp.json`
  - **Windows:** `%APPDATA%\Cursor\mcp.json`
2. Add the following:



```json
{
  "mcpServers": {
    "lusha": {
      "url": "https://mcp.lusha.com",
      "headers": {
        "x-api-key": "YOUR_LUSHA_API_KEY"
      }
    }
  }
}
```

1. Restart Cursor - Lusha tools will be available automatically in Chat and Composer.


#### Gemini CLI

Best for developers using Gemini CLI as their AI-powered terminal who need B2B data for prospecting, enrichment, or research without leaving the command line.

**Option A: Extension install (recommended)**


```bash
gemini extensions install lusha-oss/lusha-gemini-extension
```

Then set your API key as an environment variable:


```bash
export LUSHA_API_KEY=YOUR_LUSHA_API_KEY
```

Add the export to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to persist it across sessions.

**Option B: Manual `settings.json` (Streamable HTTP)**


```json
{
  "mcpServers": {
    "lusha": {
      "httpUrl": "https://mcp.lusha.com",
      "headers": {
        "Authorization": "Bearer YOUR_LUSHA_API_KEY"
      }
    }
  }
}
```

**Option C: Manual `settings.json` (npx/stdio)**


```json
{
  "mcpServers": {
    "lusha": {
      "command": "npx",
      "args": ["@lusha-org/mcp@latest"],
      "env": {
        "LUSHA_API_KEY": "YOUR_LUSHA_API_KEY"
      }
    }
  }
}
```

**Using Lusha in Gemini CLI**

Once connected, you can ask Lusha questions in natural language directly in your terminal:

- *"Find the VP of Engineering at Stripe"*
- *"Enrich this contact: jane.doe@acme.com"*
- *"Find 20 Series B SaaS companies in New York hiring in sales"*


If you installed via the extension, you also have access to slash commands:

- `/lusha:prospect` - run a prospecting search
- `/lusha:enrich` - enrich a contact or company


#### n8n

Requires n8n 1.88.0 or higher.

1. In your workflow, add an **MCP Client Tool** node
2. Set **Connection Type** to **HTTP Streamable**
3. Enter `https://mcp.lusha.com` as the URL
4. Under **Authentication**, select **Header Auth** and set:
  - **Header name:** `x-api-key`
  - **Value:** `YOUR_LUSHA_API_KEY`
5. Under **Tools to Use**, select **All Tools** or choose specific ones
6. Connect the node to your **AI Agent** node and activate the workflow


> Store your API key using n8n's built-in **Credentials** system rather than pasting it directly into node fields.


#### Other Clients

Any MCP-compatible client can connect to the Lusha MCP Server using the same pattern:

- **URL:** `https://mcp.lusha.com`
- **Header:** `x-api-key: YOUR_LUSHA_API_KEY`


Refer to your client's MCP documentation for where to configure the server URL and request headers.

## Available Tools

| Tool | Description |
|  --- | --- |
| `contacts_search` | Enrich contact data using email, LinkedIn URL, or name + company |
| `companies_search` | Retrieve company data using domain or company name |
| `prospecting_contact_filters` | Get available filter values for contact prospecting (no credits charged) |
| `prospecting_contact_search` | Search contacts by job title, seniority, location, department, and more |
| `prospecting_contact_enrich` | Enrich contacts by ID to reveal emails and phones (credits consumed) |
| `prospecting_company_filters` | Get available filter values for company prospecting (no credits charged) |
| `prospecting_company_search` | Search companies by firmographic and technographic filters |
| `prospecting_company_enrich` | Enrich companies by ID for detailed firmographic data |
| `lookalike_contacts` | Find contacts similar to a seed contact |
| `lookalike_companies` | Find companies similar to a seed company |
| `signals_contact_filters` | Get available filter values for contact signals (no credits charged) |
| `signals_contacts_search` | Resolve contacts and return recent activity signals |
| `signals_contacts_get` | Get signals for known contacts by ID |
| `signals_company_filters` | Get available filter values for company signals (no credits charged) |
| `signals_companies_search` | Resolve companies and return recent activity signals |
| `signals_companies_get` | Get signals for known companies by ID |
| `account_usage` | Check credit balance, rate-limit status, and plan info |


> Available tools may vary depending on the client used to connect.


## Troubleshooting

| Issue | Resolution |
|  --- | --- |
| Tools not showing in Claude | Confirm the connector is added and you have permission to use tools. Restart the app. |
| Tools not showing in ChatGPT | Confirm the connector is connected and enabled in the tools menu. Restart the app. |
| Tools not showing in VS Code | Make sure you're in **Agent mode** in Copilot Chat. Verify `mcp.servers` is correctly formatted in `settings.json`. |
| Tools not showing in Cursor | Verify `mcp.json` is in the correct path and is valid JSON. Restart Cursor fully. |
| Tools not showing in n8n | Confirm the MCP Client Tool node is connected to your AI Agent node and the workflow is active. Check the URL and header format. |
| Tools not showing in Gemini CLI | Verify `settings.json` is correctly formatted. Run `/mcp reload` to refresh. Restart Gemini CLI. |
| Auth errors - wrong header | For custom MCP clients, the header must be `x-api-key` (lowercase). Using `Authorization: Bearer` or any other casing will fail. |
| Auth errors - expired key | API keys can be revoked or expired. Verify your key is active in [API Hub → Manage API Keys](https://dashboard.lusha.com/api/manage-api-keys) and generate a new one if needed. |
| Partial or no results | Credits follow the same rules as the Public API - failed lookups are not charged. Check your credit balance in the Lusha admin panel. |
| OAuth not completing | If the OAuth flow stalls or errors, try disconnecting and reconnecting the connector from the directory listing. Make sure you are signed in to Lusha before starting the flow. |


## Security

- Store API keys in secure credentials (OS keychain, password manager, or your editor's secrets manager) - avoid hardcoding them in shared config files
- In n8n, use the built-in **Credentials** system rather than pasting keys directly into node fields
- Use environment variables for team setups instead of committing keys to version control
- Rotate API keys periodically and remove unused connectors
- Limit tool permissions to the minimum needed for your use case