Findymail MCP Server

MCP (Model Context Protocol) server for Findymail - enabling AI assistants to find verified B2B emails, phone numbers, and company data.

Features

This MCP server exposes the following tools:

| Tool | Description | |------|-------------| | find_email | Find verified B2B email from name + domain or LinkedIn URL | | find_employees | Find employees at a company by job title — returns name + LinkedIn URL only (no email), 1 finder credit per contact | | find_phone | Find phone number(s) from LinkedIn URL | | verify_email | Verify if an email is deliverable | | enrich_company | Get company data from domain, LinkedIn URL, or name | | reverse_email_lookup | Find person info from an email | | lookalike_search | Find similar companies from a seed domain using vector similarity | | generate_lead_list | AI-powered company discovery from a natural language description of your ideal customer | | get_lead_list_results | Retrieve results from a previously generated lead list | | list_exclusion_lists | List the exclusion lists you own or that are shared with your team | | create_exclusion_list | Create a new exclusion list | | list_exclusion_domains | List the domains held by an exclusion list, with their ids | | add_exclusion_domains | Add domains to an exclusion list (or to your global exclusions) | | remove_exclusion_domains | Remove domains from an exclusion list, by domain id |

Exclusion lists

An exclusion list holds company domains that should never show up in search results — competitors, existing customers, companies you already contacted. generate_lead_list and lookalike_search both accept exclusion_list_ids to filter them out, and generate_lead_list additionally accepts add_to_exclusion_list_id to automatically add every exported domain to a list, so a later search never returns the same companies twice.

For exclusion_list_ids:

| Value | Behaviour | |-------|-----------| | (omitted) | Every exclusion source you can reach is applied — this is the default | | [0] | Same as omitting it: your global exclusions plus every list you own or share, not just the global one | | [-1] or [] | Exclusion filtering is disabled | | [12, 15] | Only those lists are applied | | mixed | Don't: [0, 12] ignores 12 and filters on everything, [-1, 12] disables filtering entirely |

lookalike_search takes a parameter with the same name but not the same semantics: it has no [0]/[-1] markers, and an empty value means no filtering at all.

Prerequisites

• Node.js 18+
• A Findymail API key (get one here)

Installation

npm install -g findymail-mcp

Or use directly with npx:

npx findymail-mcp

Configuration

Stdio mode (local)

Each user provides their API key via environment variable.

Claude Code

claude mcp add findymail -e FINDYMAIL_API_KEY=your-api-key -- npx findymail-mcp

Or manually edit ~/.claude.json:

{
  "mcpServers": {
    "findymail": {
      "command": "npx",
      "args": ["findymail-mcp"],
      "env": {
        "FINDYMAIL_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Desktop

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "findymail": {
      "command": "npx",
      "args": ["findymail-mcp"],
      "env": {
        "FINDYMAIL_API_KEY": "your-api-key"
      }
    }
  }
}

HTTP mode (remote server)

In HTTP mode, each client passes their Findymail API key via the Authorization header. No environment variable is needed on the server.

Claude Code

claude mcp add findymail https://your-server.com/mcp -t http -H "Authorization: Bearer your-api-key"
claude mcp add findymail https://mcp.findymail.com/mcp -t http -H "Authorization: Bearer your-api-key"

Running the HTTP server

npm install express
PORT=3456 node src/http.js

Requests to /mcp without a valid Authorization: Bearer <token> header will be rejected with a 401 error.

OpenAI domain verification

Set OPENAI_APPS_CHALLENGE_TOKEN in the HTTP server environment to the exact token shown in your OpenAI submission form, then restart the server with the updated environment. The server exposes it without authentication at /.well-known/openai-apps-challenge as plain text. Without a configured token, the endpoint returns 404.

Make sure your reverse proxy forwards this path to the HTTP server, including when it normally proxies only /mcp. Check the public endpoint before clicking Verify Domain in the submission form:

curl -i https://mcp.findymail.com/.well-known/openai-apps-challenge

It must return HTTP 200 with only the token in the response body. Leave the form's Challenge Base URL blank to verify on the MCP hostname. Do not replace another active app's token on the same hostname.

Optional settings

| Variable | Default | Effect | |---|---|---| | FINDYMAIL_API_TIMEOUT_MS | 100000 | How long a call to the Findymail API may take before the tool gives up. A value that is not a whole number between 1 and 2147483647 is ignored, with a warning in the logs. |

Usage Examples

Once configured, you can ask your AI assistant:

• "Find the email for John Smith at Acme Corp"
• "Find 3 sales managers at stripe.com and get their emails"
• "What's the phone number for the CEO of findymail.com?"
• "Verify if [email protected] is a valid email"
• "Get company information for stripe.com"
• "Find me 10 marketing managers at SaaS companies in San Francisco"
• "Find companies similar to stripe.com in the same country"
• "Create an exclusion list called Competitors and add stripe.com and brex.com to it"
• "Find 50 fintech companies in Europe, excluding my Competitors list, and add the results to it so I don't get them again"

API Key

Get your API key from Findymail Settings.

Each API call consumes credits from your Findymail account.

Development

# Clone the repo
git clone https://github.com/Findymail/findymail-mcp.git
cd findymail-mcp

# Install dependencies
npm install

# Run locally
FINDYMAIL_API_KEY=your-key npm start

# Run the tests (Node 18.2+, no network access or API key needed)
npm test

Deployment

See PUBLISHING.md for the npm release process.

License

MIT