# š LeadMagic MCP Server
<div align="center">
**ā” The Ultimate Model Context Protocol Server for B2B Data Enrichment**
*Seamlessly integrate LeadMagic's complete API suite with Claude, Cursor, Windsurf, and all MCP-compatible AI tools*
[](https://www.npmjs.com/package/leadmagic-mcp-server)
[](https://www.npmjs.com/package/leadmagic-mcp-server)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io)
[](https://github.com/LeadMagic/leadmagic-mcp)
[](https://github.com/LeadMagic/leadmagic-mcp/security)
[](https://github.com/LeadMagic/leadmagic-mcp/stargazers)
[](https://github.com/LeadMagic/leadmagic-mcp/issues)
[](https://github.com/LeadMagic/leadmagic-mcp/network/members)
[](https://github.com/LeadMagic/leadmagic-mcp/commits/main)
---
**šÆ 19 Powerful Tools ā¢ š„ Zero Configuration ā¢ ā” One-Line Setup ā¢ š”ļø Enterprise Security**
</div>
---
## š Table of Contents
- [š Super Easy Installation](#-super-easy-installation)
- [š ļø Available Tools](#ļø-available-tools)
- [š” Usage Examples](#-usage-examples)
- [š Supported MCP Clients](#-supported-mcp-clients)
- [š§ Development Setup](#-development-setup)
- [šļø Architecture](#ļø-architecture)
- [š API Reference](#-api-reference)
- [š Security & Best Practices](#-security--best-practices)
- [šÆ Installation Matrix](#-installation-matrix)
- [š¤ Support & Resources](#-support--resources)
- [š License](#-license)
- [šāāļø Contributing](#ļø-contributing)
- [š Updates & Changelog](#-updates--changelog)
---
> šÆ **Access all 19 LeadMagic API endpoints through the Model Context Protocol for seamless integration with Claude, Cursor, Windsurf, Continue.dev, and other MCP-compatible AI tools.**
## š Super Easy Installation
### ā” Option 1: Interactive Installer (Recommended)
The easiest way to get started - works on **macOS**, **Windows**, and **Linux**. Our new interactive installer, built with React and Ink, makes setup a breeze.
```bash
# š„ Using npx (no installation required)
npx leadmagic-mcp-server install
```
**āØ The installer will:**
- ā
**Validate your API key** in real-time and show your remaining credits.
- ā
Automatically detect and configure your preferred AI tool (Claude, Cursor, VS Code, etc.).
- ā
Create all necessary config files and a local `.env` for development.
- ā
Provide usage examples and helpful links.
### š± Option 2: Quick Manual Setup
If you prefer manual setup or are using a client like **Aider**, you can add the server configuration directly to your client's settings file. The interactive installer provides copy-pasteable snippets for this.
Run the installer and choose the "Other (Manual Setup)" option:
```bash
npx leadmagic-mcp-server install
```
### š Get Your API Key
1. š Visit [LeadMagic Dashboard](https://app.leadmagic.io/dashboard/api-keys)
2. š Sign up for free (if needed)
3. š Generate your API key
4. š Paste it into the interactive installer when prompted.
### ā” npx Usage (Zero Installation)
You can use the server without installing, which is great for quick tests or containerized environments:
```bash
# š Run directly with your API key
LEADMAGIC_API_KEY=your-key npx leadmagic-mcp-server
# š Run the interactive installer
npx leadmagic-mcp-server install
# ā Check available commands
npx leadmagic-mcp-server --help
```
---
## š ļø Available Tools
### š Core Operations (3 tools)
- š³ `get_credits` - Check API credit balance
- ā
`validate_email` - Validate email deliverability and get company info
- š§ `find_email` - Find verified email addresses by name and company
### š¢ Profile & Company Intelligence (5 tools)
- š¤ `search_profile` - Get full B2B profile details (300 req/min)
- š `search_company` - Search companies by domain, name, or profile URL
- š± `find_mobile` - Find mobile phone numbers from profiles/emails
- š `email_to_profile` - Find B2B profile URLs from work emails
- š° `get_company_funding` - Get funding, financials, and competitor data
### āļø Advanced Email Finding (2 tools)
- šØ `find_personal_email` - Find personal emails from B2B profiles
- š `social_to_work_email` - Find work emails from social profiles
### š¼ Job & Employee Intelligence (5 tools)
- š `find_jobs` - Search job postings with advanced filters
- š `find_role` - Find specific roles within companies
- š„ `find_employees` - Find employees of specific companies
- š `get_job_countries` - Get available job search countries
- š `get_job_types` - Get available job types for filtering
### š± Advertisement Intelligence (4 tools)
- š `search_google_ads` - Search Google Ads by company
- š `search_meta_ads` - Search Meta (Facebook/Instagram) Ads
- š `search_b2b_ads` - Search B2B advertising campaigns
- š `get_b2b_ad_details` - Get detailed B2B ad information
---
## š” Usage Examples
Once installed, you can use natural language commands in your AI tool:
### š§ Email Operations
```
"Find the email for John Doe at Microsoft"
"Validate the email john@acme.com"
"Find personal email for B2B profile https://linkedin.com/in/johndoe"
```
### š¢ Company Intelligence
```
"Search for Tesla company information"
"Get funding information for Stripe"
"Find employees at OpenAI who work in engineering"
```
### š¼ Job & Recruitment
```
"Find software engineer jobs at tech companies"
"Search for product manager roles in San Francisco"
"Find mobile number for this B2B profile"
```
### š± Competitive Analysis
```
"Search for Google Ads from competitor.com"
"Find Meta ads for company XYZ"
"Get B2B advertising campaigns for stripe.com"
```
---
## š§ Development Setup
### š Prerequisites
- š¦ Node.js 18.0.0 or higher
- š LeadMagic API key from [leadmagic.io](https://leadmagic.io)
### š» Local Development
```bash
# š„ Clone the repository
git clone https://github.com/LeadMagic/leadmagic-mcp.git
cd leadmagic-mcp
# š¦ Install dependencies
npm install
# š Create environment file
echo "LEADMAGIC_API_KEY=your-api-key-here" > .env
# š Start development server
npm run dev
# šļø Build for production
npm run build
# ā
Run validation
npm run validate
```
### š Testing with MCP Inspector
```bash
# š Start the MCP inspector
npm run inspector
# š Open the provided URL in your browser to test all tools
```
---
## š Supported MCP Clients
| Client | Installation | Status | Notes |
|--------|-------------|--------|-------|
| š¤ **Claude Desktop** | Interactive installer or manual config | ā
Fully Supported | Official Anthropic client |
| šÆ **Cursor (Cline)** | Interactive installer or VS Code settings | ā
Fully Supported | Requires Cline extension |
| š **Windsurf** | Interactive installer or manual config | ā
Fully Supported | Codeium's AI IDE |
| š **Continue.dev** | Interactive installer or config file | ā
Fully Supported | Open source coding assistant |
| š» **VS Code (Cline)** | VS Code settings.json | ā
Fully Supported | Requires Cline extension |
| š» **VS Code (Continue)** | Continue extension config | ā
Fully Supported | Requires Continue extension |
| ā” **Zed Editor** | Interactive installer or settings | ā
Fully Supported | Modern code editor |
| š¤ **Aider** | Manual Configuration | ā
Supported | AI pair programming in your terminal |
| āØ **Augment Code** | Manual Configuration | ā
Supported | AI coding assistant |
| š **Any MCP Client** | Manual configuration | ā
Supported | Standard MCP protocol |
---
## šļø Architecture
### š ļø Technology Stack
- ā” **Runtime**: Node.js 18+
- š **Language**: TypeScript with strict type checking
- š **MCP SDK**: @modelcontextprotocol/sdk v1.0.0+
- š **HTTP Client**: Axios with comprehensive error handling
- ā
**Validation**: Zod schemas for all API inputs/outputs
- š§ **Development**: ESLint, Prettier, Jest for testing
### š Project Structure
```
āāā src/
ā āāā index.ts # š Main entry point and CLI command handling
ā āāā server.ts # š MCP server implementation with all 19 tools
ā āāā client.ts # š LeadMagic API client wrapper
ā āāā types.ts # š TypeScript types and Zod schemas
ā āāā install.tsx # šØ The new interactive installer (React/Ink)
āāā dist/ # š¦ Compiled JavaScript output
āāā .env.example # š Environment configuration example
āāā README.md # š This file
```
---
## š API Reference
### š¤ Field Naming Convention
**All fields use snake_case** (matching LeadMagic API):
```json
{
"first_name": "John",
"company_name": "Acme Corp",
"email_status": "valid"
}
```
### š Authentication
Include your API key in requests:
```bash
X-API-Key: your-leadmagic-api-key
```
### ā±ļø Rate Limits
- š¤ **Profile Search**: 300 requests/minute
- š **Other endpoints**: Standard rate limits apply
### ā Error Handling
Consistent error format across all endpoints:
```json
{
"error": "Bad Request",
"message": "API key is missing or invalid."
}
```
---
## š Credit Consumption
| Endpoint | Credits | Notes |
|----------|---------|--------|
| š³ `/credits` | 0 | Free to check |
| ā
`/email-validate` | 0.05 | Very cost-effective |
| š§ `/email-finder` | 1 | Standard rate |
| š± `/mobile-finder` | 5 | Only if found |
| š¤ `/profile-search` | 1 | Rate limited (300/min) |
| š `/b2b-profile` | 10 | Higher cost for reverse lookup |
| š° `/company-funding` | 4 | Premium intelligence |
| š¼ `/jobs-finder` | 1 per job | Based on results |
| š `/google/searchads` | 1 per ad | Based on ads found |
| š All others | 1-2 | Standard rates |
---
## š Security & Best Practices
ā
**No API keys in code** - Always use environment variables
ā
**Type-safe requests** - Full TypeScript coverage with Zod validation
ā
**Error handling** - Comprehensive error catching and user-friendly messages
ā
**Rate limiting** - Respects LeadMagic API rate limits
ā
**Secure defaults** - Production-ready configuration out of the box
ā
**Interactive installer** - No manual config file editing required
---
## šÆ Installation Matrix
Choose your installation method based on your setup:
| Scenario | Command | Best For |
|----------|---------|----------|
| š **First time user** | `npx leadmagic-mcp-server install` | Easiest setup |
| š¤ **Claude Desktop** | Interactive installer ā Option 1 | Most popular |
| šÆ **Cursor/VS Code** | Interactive installer ā Option 2/5 | Developers |
| š **Multiple clients** | Interactive installer ā Option 7 | Power users |
| ā” **Quick test** | `LEADMAGIC_API_KEY=key npx leadmagic-mcp-server` | Testing |
| š» **Local development** | Clone repo + `.env` file | Contributors |
---
## š¤ Support & Resources
- š **API Documentation**: [docs.leadmagic.io](https://docs.leadmagic.io)
- š **Official Website**: [leadmagic.io](https://leadmagic.io)
- š **Dashboard**: [app.leadmagic.io](https://app.leadmagic.io)
- š **Support**: support@leadmagic.io
- š **Issues**: [GitHub Issues](https://github.com/LeadMagic/leadmagic-mcp/issues)
- š¬ **Community**: [Join our Discord](https://discord.gg/leadmagic)
- š **Source Code**: [GitHub Repository](https://github.com/LeadMagic/leadmagic-mcp)
---
## š License
MIT License - see the [LICENSE](LICENSE) file for details.
---
## šāāļø Contributing
We welcome contributions! Here's how to get started:
1. š“ Fork the repository
2. šæ Create a feature branch: `git checkout -b feature/new-feature`
3. āØ Make your changes and add tests
4. ā
Run validation: `npm run validate`
5. š¾ Commit your changes: `git commit -am 'Add new feature'`
6. š¤ Push to the branch: `git push origin feature/new-feature`
7. š Submit a pull request
### š Bug Reports
Found a bug? Please [open an issue](https://github.com/LeadMagic/leadmagic-mcp/issues/new?assignees=&labels=bug&template=bug_report.md&title=) with:
- š Clear description of the issue
- š Steps to reproduce
- š» Your environment details
- š Expected vs actual behavior
### š” Feature Requests
Have an idea? [Request a feature](https://github.com/LeadMagic/leadmagic-mcp/issues/new?assignees=&labels=enhancement&template=feature_request.md&title=) with:
- š Clear description of the feature
- šÆ Use case and benefits
- š Any implementation ideas
---
## š Updates & Changelog
### v1.0.1 (Latest) - June 27, 2025
- šØ Redesigned README with professional and impactful header
- š¦ Enhanced package.json with better description and keywords
- šÆ Improved branding and visual presentation
- š§ Documentation polish and terminology consistency
- š·ļø Added enhanced badges with security verification
- š Overall professional presentation improvements
### v1.0.0 - June 27, 2025
- āØ Interactive installer for all major AI tools
- ā
Support for Claude Desktop, Cursor, Windsurf, Continue.dev, VS Code, Zed
- š§ All 19 LeadMagic API endpoints implemented
- šÆ Zero-config npx usage
- š Enhanced security and error handling
- š Comprehensive documentation
[View complete changelog](CHANGELOG.md)
---
<div align="center">
**š Built with the [official LeadMagic OpenAPI specification](https://github.com/LeadMagic/leadmagic-openapi) for 100% API accuracy**
---
### š Star us on GitHub ā¢ š Report Issues ā¢ š” Request Features
[](https://github.com/LeadMagic/leadmagic-mcp)
[](https://www.npmjs.com/package/leadmagic-mcp-server)
[](https://discord.gg/leadmagic)
**Made with ā¤ļø by the LeadMagic team**
</div>
