prospeo-mcp-server

Prospeo MCP Server

Official Model Context Protocol (MCP) server for Prospeo — giving AI tools native access to B2B lead search and enrichment.

Works with any MCP-compatible client: Claude, Cursor, Windsurf, Claude Code, and more.

Features

• Search Suggestions — Free helper to resolve canonical filter values for locations, job titles, technologies, industries, NAICS, and SIC codes (no credits consumed)
• Enrich Person — Find professional email and mobile phone from a name, LinkedIn URL, or email
• Bulk Enrich People — Enrich up to 25 people in a single call — the canonical follow-up to search_person
• Enrich Company — Get full company profile: headcount, industry, revenue, tech stack, funding, social links
• Bulk Enrich Companies — Enrich up to 25 companies in a single call from a list of names or domains
• Search People — Query Prospeo's professional database with filters (job title, seniority, location, company size, etc.)
• Search Companies — Query Prospeo's company database with filters (industry, headcount, technology, revenue, etc.)
• Account Info — Check credits remaining, plan, and renewal date (free, no credits consumed)

Quick Start

Option 1: Hosted Server (Recommended)

Connect directly to Prospeo's hosted MCP server — no installation needed.

Server URL:

https://mcp.prospeo.io

Authentication is handled via OAuth or by passing your API key in the X-KEY header. Supported by Claude.ai, Claude Desktop, and other remote MCP clients.

Option 2: Local via npx

Run the server locally in stdio mode. Requires Node.js 18+.

Claude Code

claude mcp add prospeo --env PROSPEO_API_KEY=your_api_key -- npx -y @prospeo/prospeo-mcp-server

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "prospeo": {
      "command": "npx",
      "args": ["-y", "@prospeo/prospeo-mcp-server"],
      "env": {
        "PROSPEO_API_KEY": "your_api_key"
      }
    }
  }
}

Cursor / Windsurf

Add to your MCP settings (refer to your client's documentation):

{
  "prospeo": {
    "command": "npx",
    "args": ["-y", "@prospeo/prospeo-mcp-server"],
    "env": {
      "PROSPEO_API_KEY": "your_api_key"
    }
  }
}

Configuration

Environment Variables

Variable	Required	Default	Description
PROSPEO_API_KEY	Yes (stdio mode)	—	Your Prospeo API key. Get one at app.prospeo.io/api
PROSPEO_API_BASE_URL	No	https://api.prospeo.io	API base URL; legacy endpoints remain relative to this base
PROSPEO_API_V2_PREFIX	No	/api/v2	Must match backend API_V2_STR, for example /test-api
LOG_LEVEL	No	INFO	Logging level: DEBUG, INFO, WARN, ERROR

Tools

Backend-provided tools

At startup, both stdio and hosted HTTP load POST /api/v2/mcp/tools from the configured Prospeo API. The table supplies the tool names, strict input schemas, annotations, and public endpoint bindings. Calls are validated against those schemas and forwarded with the caller's API key. Hosted connections share the compiled startup table; each call retains its own authenticated key.

The table covers enabled, implemented canonical server tools with public bindings, excluding internal helpers, browser tools, and legacy aliases. Coverage follows the backend catalog rather than a fixed tool count. The eight compatibility tools documented below remain available; canonical get_usage_and_credits remains available as get_account_info.

Metadata loads without user credentials from the API base URL plus PROSPEO_API_V2_PREFIX plus /mcp/tools. The prefix defaults to /api/v2 and must match backend API_V2_STR. For /test-api, startup fetches POST /test-api/mcp/tools. Generated calls use the exact server-root path in the table; the prefix is not added again. Keep the base URL unchanged so legacy tools continue calling their existing root-level endpoints.

An API-key call directly authorizes the operation, including a possible credit charge. The prospeo/approvalRecommended and prospeo/credits metadata allow clients to present their own confirmation. Find Mobile uses normal member credit limits and returns a receipt and record link; the revealed phone value is read in the authenticated product. Thread search searches only the key owner's private chats.

If the table cannot be fetched or validated, the server starts with the eight compatibility tools and records the degradation. Restart the MCP process after a backend catalog release to load newly shipped tools. Coordinate backend, Assistant, and MCP availability in the same release window.

Generated tool responses preserve the public JSON projection. Failed tool calls set MCP isError: true and return a JSON error with code and message.

For contract verification, set PROSPEO_PUBLIC_TABLE_PATH to the JSON table emitted by the backend public-tool tests and run npm test. Also run npm run build and npm run build:http.

search_suggestions

Resolve canonical filter values before building a search. Free endpoint — does not consume credits. Rate limited to 15 req/sec.

Call this first whenever the user mentions a location, technology, industry, job title, or NAICS / SIC code — guessing strings (e.g. "SF" vs "San Francisco, California, United States") causes empty searches.

Supported types: location, job_title, technology, industry, naics, sic.

enrich_person

Find the professional email address and/or mobile phone number for a person. Use bulk_enrich_person instead when you have multiple people to enrich (same per-record cost, one call instead of many).

Required input (at least one):

• linkedin_url — Person's LinkedIn profile URL
• email — Known email address
• person_id — From a prior search_person result
• first_name + last_name + company_name or company_website

bulk_enrich_person

Enrich up to 25 people in a single call — the canonical follow-up to search_person. Pass each result's person_id as a record; the matched.identifier in the response equals that person_id so you can stitch results back to the original list.

Per-record credit cost is identical to enrich_person (1 credit per matched email, 10 per matched email + mobile). Returns a compact response per record (no job_history, no skills, abbreviated company summary) — use enrich_person if you need the full profile for a specific person.

enrich_company

Get a full company profile including headcount, industry, revenue, tech stack, funding, social links, attributes, and job postings.

Required input (at least one):

• company_website (recommended, most accurate)
• company_name
• company_linkedin_url
• company_id — From a prior search or enrich result

bulk_enrich_company

Enrich up to 25 companies in a single call — the canonical lookup tool when you already have a list of company names or domains (CRM exports, account lists, competitor maps). Returns the full company profile per match. 1 credit per matched company. identifier defaults to company_id when provided so chaining from search_company results is trivial.

search_person

Search Prospeo's professional database using typed filters. Returns up to 25 results per page. Costs 1 credit per page of results.

Filters include: person_job_title, person_seniority, person_location_search, company_industry, company_headcount_range, company_technology, person_search, person_name, person_job_change, person_contact_details, and more.

search_company

Search Prospeo's company database using typed filters. Returns up to 25 results per page. Costs 1 credit per page of results.

Filters include: company_industry, company_headcount_range, company_location_search, company_technology, company_revenue, company_funding, company_intent, company_icp, company_lookalike, company_key_execs, company_website_traffic, company_integrations, and more.

get_account_info

Check your Prospeo account status — credits remaining, plan name, renewal date, and team size. Free endpoint, no credits consumed.

Examples

Example 1: Find someone's email from LinkedIn

Prompt:

Find the professional email for the person at linkedin.com/in/johndoe

What happens: The server calls enrich_person with the LinkedIn URL and returns the person's verified professional email, current job title, company, and phone number if available.

Example 2: Research a company before outreach

Prompt:

Give me a full profile of stripe.com — headcount, funding, tech stack, everything

What happens: The server calls enrich_company with the domain and returns the company's industry, employee count, revenue range, technologies used, funding rounds, social links, and headquarters location.

Example 3: Build a lead list with filters

Prompt:

Find VP-level people in SaaS companies with 50-200 employees in the US

What happens: The server calls search_person with seniority, industry, headcount, and location filters. Returns up to 25 matching professionals per page with name, title, company, email, and LinkedIn URL.

Example 4: Find companies using a specific technology

Prompt:

Search for companies that use Salesforce and have more than 500 employees

What happens: The server calls search_company with technology and headcount filters. Returns matching companies with domain, industry, size, location, and tech stack details.

Example 5: Check remaining credits

Prompt:

How many Prospeo credits do I have left?

What happens: The server calls get_account_info and returns your current plan, credits remaining, renewal date, and team size — without consuming any credits.

Authentication

Hosted server (mcp.prospeo.io)

The hosted server supports two authentication methods:

1. OAuth 2.0 — Used by Claude.ai and Claude Desktop. The OAuth consent flow is handled automatically when connecting through the MCP directory.
2. API Key header — Pass your API key in the X-KEY header for direct programmatic access.

Local server (stdio mode)

Pass your API key via the PROSPEO_API_KEY environment variable. The server validates the key on startup and exits with a clear error if it's missing.

Privacy Policy

See our privacy policy: https://prospeo.io/privacy-policy

Support

• Email: [email protected]
• Helpdesk: https://help.prospeo.io
• MCP Documentation: https://prospeo.io/mcp-docs
• REST API Documentation: https://prospeo.io/api-docs
• Issues: https://github.com/prospeo-v2/prospeo-mcp-server/issues

Releasing

Run the Publish workflow from the Actions tab on main and pick patch, minor or major. It bumps the version in package.json and server.json, publishes to npm and the MCP Registry, then commits and tags the release.

License

MIT