🚀 LeadMagic MCP Server

⚡ 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

🎯 19 Powerful Tools • 🔥 Zero Configuration • ⚡ One-Line Setup • 🛡️ Enterprise Security

📖 Table of Contents

• 🚀 Super Easy Installation

• 🛠️ Available Tools

• 💡 Usage Examples

• 🌐 Supported MCP Clients

• 🔧 Development Setup

• 🏗️ Architecture

• 📊 API Reference

• 🔒 Security & Best Practices

• 🎯 Installation Matrix

• 🤝 Support & Resources

• 📄 License

• 🙋‍♀️ Contributing

• 🔄 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.

✨ 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:

🔑 Get Your API Key

1. 🌐 Visit LeadMagic Dashboard

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:

🛠️ 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

🏢 Company Intelligence

💼 Job & Recruitment

📱 Competitive Analysis

🔧 Development Setup

📋 Prerequisites

• 📦 Node.js 18.0.0 or higher

• 🔑 LeadMagic API key from leadmagic.io

💻 Local Development

🔍 Testing with MCP Inspector

🌐 Supported MCP Clients

🏗️ 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

📊 API Reference

🔤 Field Naming Convention

All fields use snake_case (matching LeadMagic API):

🔐 Authentication

Include your API key in requests:

⏱️ Rate Limits

• 👤 Profile Search: 300 requests/minute

• 📊 Other endpoints: Standard rate limits apply

❌ Error Handling

Consistent error format across all endpoints:

📈 Credit Consumption

🔒 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:

🤝 Support & Resources

• 📚 API Documentation: docs.leadmagic.io

• 🌐 Official Website: leadmagic.io

• 📊 Dashboard: app.leadmagic.io

• 🆘 Support: support@leadmagic.io

• 🐛 Issues: GitHub Issues

• 💬 Community: Join our Discord

• 🐙 Source Code: GitHub Repository

📄 License

MIT License - see the 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 with:

• 📝 Clear description of the issue

• 🔄 Steps to reproduce

• 💻 Your environment details

• 📋 Expected vs actual behavior

💡 Feature Requests

Have an idea? Request a feature 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

🎉 Built with the

🌟 Star us on GitHub • 🐛 Report Issues • 💡 Request Features

Made with ❤️ by the LeadMagic team