# b2bleads-mcp [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/gtovtya/b2bleads-mcp  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1416  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/b2bleads-mcp

## Description
Search and enrich B2B business leads by industry and city.

## Tools
Capabilities this server exposes over MCP:

- **search_leads** — Search for companies and business contacts in real time by industry, city, and other filters. Returns a ready-to-use list of leads (name, address, phone, website, and email where available). Use this whenever the user asks to find, list, or collect businesses/companies for sales, outreach, or research.
- **search_leads_advanced** — ⚠️ ELEVATED COST: consumes 9x the quota of a single search_leads call. Only use this when the user explicitly wants more results than a regular search_leads call returned for one city, or asks to exhaustively cover a city — never as a default or first attempt; always try search_leads first. Tiles the given city into a 3x3 grid of sub-searches server-side to go beyond the normal ~20-60 result ceiling and return up to ~180 deduplicated businesses in one city. Requires an exact city name only (not the free-text query or industry) — passing a full sentence instead of a city name can cause it to geocode the wrong place and return zero results. Does not support pagination. Read-only: it never saves, creates, updates, or deletes leads.
- **list_industries** — List the predefined industry categories that can be used as the `industry` filter in search_leads.
- **list_saved_lists** — List all of the user's saved lead lists (read-only) — id, name, and lead count for each, not the leads themselves. Use this when the user asks what they've already saved, or which lists exist. Call get_saved_list with a list's id to fetch its full leads.
- **get_saved_list** — Get one saved lead list by ID, including its full set of saved leads (read-only).
- **find_email** — Look up a best-effort contact email for a single business website (checks the homepage and common contact pages). Use this for one specific website, e.g. from a saved list or CSV, rather than re-running search_leads. May return a null email if none could be found; this tool never fabricates an address.
- **account_get_usage** — Get how much of the connected B2BLeads account's monthly search quota has been used and how much remains for the current billing period. Use account_get_usage_limit for the plan's total monthly limit and renewal date.
- **account_get_usage_limit** — Get the connected B2BLeads account's total monthly search quota and when the current billing period renews. Use account_get_usage for how much of it has been used so far.
- **list_saved_searches** — List the connected B2BLeads account's saved search alerts (recurring searches set up to auto-run and save results to a list). Read-only — never creates, modifies, or deletes one.
- **get_search_history** — Get the connected B2BLeads account's recent search history (up to the last 200 searches: query text, result count, date). Use this when the user asks what they searched for before. Read-only.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "b2bleads-mcp": {
    "command": "npx",
    "args": ["-y","b2bleads-mcp"],
    "env": {
      "B2BLEADS_API_KEY": "",
      "B2BLEADS_API_URL": ""
    }
  }
}
```

**Requires environment variables:** `B2BLEADS_API_KEY`, `B2BLEADS_API_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What b2bleads-mcp MCP server does

The b2bleads-mcp MCP server exposes the B2BLeads REST API as tools for MCP-compatible agents. It searches for companies and business contacts using free-text queries, industries, cities or regions, distance, ratings, business status, pricing, websites, verification, language, and result ordering. Search results can include company name, address, phone, website, rating, and email when available.

The standard search accepts at least one of a free-text query, industry, or city. Results can be limited to 1–20 records per call and continued with a pagination token. Searches can also append results to an existing saved list or create/find a list by name.

## How it works

The package runs as a local MCP process and sends requests to B2BLeads. An agent invokes the available tools, while the server handles communication with the API and returns the API response or an error such as a quota or rate-limit failure.

For larger city searches, `search_leads_advanced` divides a city into a 3-by-3 grid of sub-searches and returns up to approximately 180 deduplicated businesses. This operation costs nine times the quota of one regular search, does not provide pagination, and should be reserved for cases where the normal search does not return enough results or exhaustive city coverage is needed. Its `city` value should contain only the city or region name.

Saved-list tools let an agent first retrieve list IDs, names, and counts, then fetch the complete leads for one selected list. `find_email` checks a supplied business website, including its homepage and common contact pages, for a possible contact email.

## Setup and configuration

The b2bleads-mcp MCP server requires Node.js 18 or newer, a B2BLeads account, and an API key. It can be launched without a local package installation using:

```text
npx -y b2bleads-mcp
```

Configure the MCP client to run that command and set `B2BLEADS_API_KEY` in its environment. The key is created in the B2BLeads dashboard after choosing a plan. `B2BLEADS_API_URL` is optional and can replace the default API base URL, `https://api.b2bleadsapi.com`.

The documented configuration works with Claude Desktop, Claude Code, Cursor, and other MCP-compatible clients. In Cursor, the same server definition can be placed in project or global MCP settings. Claude Desktop uses its MCP configuration file, while Claude Code can add the server through its MCP command.

## Tools and capabilities

- `search_leads`: Runs a real-time search with geographic, industry, rating, business-status, website, verification, price, language, ranking, pagination, and saved-list options.
- `search_leads_advanced`: Expands a city search across nine geographic areas for broader coverage, with the elevated quota cost described above.
- `list_industries`: Returns the predefined categories accepted by the regular search's industry filter.
- `list_saved_lists`: Returns saved-list IDs, names, and lead counts without returning the leads themselves.
- `get_saved_list`: Retrieves all saved leads for a specified list ID.
- `find_email`: Performs a best-effort lookup for one website and may return no email. This requires a paid B2BLeads plan, starting with Starter.

## Limitations and notes

The b2bleads-mcp MCP server depends on an active B2BLeads account, plan, API key, quota, and rate limits. Search quota is consumed by each search, and API quota or rate-limit errors are surfaced as tool errors. The advanced search is not a general replacement for the regular search because it costs nine times as much and cannot paginate.

Email discovery is not guaranteed: `find_email` may return `null` when no address is found. It is intended for one website at a time rather than repeating a broad lead search. The advanced tool also requires a city value and can produce incorrect geocoding if the input includes a complete search phrase instead of only the place name.

_Full upstream README: https://allmcps.com/mcp/b2bleads-mcp/readme_