Apollo.io MCP Server & CLI

A Model Context Protocol (MCP) server and command-line interface for Apollo.io. This package provides:

• MCP Server: Integrates Apollo.io with Claude Desktop for conversational access to B2B data
• CLI Tool: Command-line interface for direct API access via terminal

Both tools provide access to Apollo's comprehensive B2B database for people and company search, enrichment, and insights.

• Apollo.io MCP Server & CLI
  • Features
  • CLI Tool
  • Claude Desktop Setup
    • Step 1: Get Your Apollo API Key
    • Step 2: Configure Claude Desktop
      • Using npx (Recommended)
      • If using a Developer Installation (unlikely)
    • Step 3: Test the Integration
  • Manual Setup (For Developers)
    • Claude Desktop Configuration for Source Installation
  • Available Tools
    • Search Tools
      • apollo_search_people
      • apollo_search_companies
    • Enrichment Tools
      • apollo_enrich_person
      • apollo_enrich_company
      • apollo_bulk_enrich_people
      • apollo_bulk_enrich_organizations
    • Additional Tools
      • apollo_get_organization_job_postings
      • apollo_get_complete_organization_info
      • apollo_search_news_articles
  • Filter Reference
    • Company Search Filters
    • People Search Filters
  • Claude Desktop Integration
  • Testing
    • Run all tests:
    • Run CLI integration test:
    • Test specific filters:
    • Test MCP Inspector integration:
    • Test with MCP Inspector (Visual Testing Tool)
      • Setup Inspector:
      • MCP Inspector Configuration
      • Run Inspector (UI Mode):
      • Run Inspector (CLI Mode):
      • Inspector Features:
  • Environment Setup
  • Troubleshooting
    • Common Issues
    • Filter Best Practices
  • API References
  • Contributing
  • License

Features

• Apollo Org and People Search covering all major Apollo.io API endpoints
• Claude Desktop optimized Simple ICP discovery
• Advanced filtering with Apollo.io API parameter mapping
• CLI Tool for command-line access to Apollo.io API
• TypeScript SDK for programmatic access

CLI Tool

The package includes a powerful command-line interface for direct API access:

# Install globally
npm install -g @thevgergroup/apollo-io-mcp

# Search for people (person_titles required)
apollo-io-cli search-people --person_titles "Manager,Director" --person_locations "Virginia"

# Find specific person by name (enrichment)
apollo-io-cli enrich-person --first_name "John" --last_name "Doe" --organization_name "Company"

# Other examples
apollo-io-cli enrich-person --email "tim@apollo.io"
apollo-io-cli search-companies --q "technology" --organization_num_employees_ranges "51,200"
apollo-io-cli org-jobs --id "5e66b6381e05b4008c8331b8"

Important: People search requires --person_titles. To find someone by name, use enrichment instead.

See CLI.md for complete CLI documentation, examples, and usage guide.

Claude Desktop Setup

This MCP server is designed to work seamlessly with Claude Desktop. Follow these steps to get started:

Step 1: Get Your Apollo API Key

Before setting up the MCP server, you'll need an Apollo API key:

1. Launch Apollo and go to Settings > Integrations
2. Find the API option and click Connect
3. Click "API keys" to view or create new API keys, then click Create new key
4. Name your API key (e.g., "Claude Desktop Integration") and add a description
5. Select the endpoints you need access to, or toggle "Set as master key" for full access
6. Click "Create API key" and copy the key to a safe location

Important: Keep your API key secure. Anyone with access to this key can make API calls through your Apollo account.

Note: API access is dependent on your Apollo pricing plan. Check Apollo's pricing page for details on API limits and features available with your plan.

For more details, see the Apollo API Key Creation Guide.

Step 2: Configure Claude Desktop

Add this configuration to your Claude Desktop MCP settings:

Using npx (Recommended)

{
  "mcpServers": {
    "apollo": {
      "command": "npx",
      "args": ["@thevgergroup/apollo-io-mcp@latest"],
      "env": {
        "APOLLO_API_KEY": "your-actual-api-key-here",
        "APOLLO_BASE_URL": "https://api.apollo.io/api/v1"
      }
    }
  }
}

If using a Developer Installation (unlikely)

{
  "mcpServers": {
    "apollo": {
      "command": "node",
      "args": ["./node_modules/@thevgergroup/apollo-io-mcp/dist/server.js"],
      "env": {
        "APOLLO_API_KEY": "your-actual-api-key-here",
        "APOLLO_BASE_URL": "https://api.apollo.io/api/v1"
      }
    }
  }
}

Replace your-actual-api-key-here with the API key you created in Step 1.

Step 3: Test the Integration

Once configured, restart Claude Desktop and try asking:

• "Search for software companies in California with 50-200 employees"
• "Find C-level executives in the healthcare industry"
• "Enrich the company data for google.com"

Manual Setup (For Developers)

If you prefer to install from source or need to modify the code:

1. Clone the repository:

git clone https://github.com/thevgergroup/apollo-io-mcp
cd apollo-io-mcp

2. Install dependencies:

npm install

3. Set up environment variables:

# Only if .env doesn't already exist
cp env.example .env

4. Edit .env and add your Apollo.io API key:

APOLLO_API_KEY=your-actual-api-key-here
APOLLO_BASE_URL=https://api.apollo.io/api/v1

5. Build the project:

npm run build

Claude Desktop Configuration for Source Installation

{
  "mcpServers": {
    "apollo": {
      "command": "node",
      "args": ["/path/to/apollo-io-mcp/dist/server.js"],
      "env": {
        "APOLLO_API_KEY": "your-actual-api-key-here",
        "APOLLO_BASE_URL": "https://api.apollo.io/api/v1"
      }
    }
  }
}

Available Tools

Search Tools

apollo_search_people

Search for people in Apollo's database with advanced filtering options. The tool provides comprehensive filter documentation to help target specific roles, locations, seniority levels, and companies.

Available Filters:

• locations: Person locations (cities, states, countries)
• seniority: Seniority levels (e.g., ["C-Level", "VP", "Director"])
• titles: Job titles (e.g., ["CEO", "CTO", "Sales Manager"])
• departments: Departments (e.g., ["Engineering", "Sales", "Marketing"])
• company_domains: Company domains (e.g., ["google.com", "microsoft.com"])
• industries: Industries (e.g., ["Software", "Healthcare", "Finance"])
• technologies: Technologies they use (e.g., ["python", "react", "salesforce"])

Example:

{
  "query": "CEO",
  "filters": {
    "locations": ["California"],
    "seniority": ["C-Level"],
    "industries": ["Software", "SaaS"]
  },
  "per_page": 10
}

apollo_search_companies

Search for companies/organizations with comprehensive filtering options. The tool provides detailed documentation for all available filters to help target specific company types, locations, sizes, and industries.

Available Filters:

• organization_locations: Company locations (most effective filter)
• organization_not_locations: Exclude specific locations
• q_organization_keyword_tags: Industry keywords (crucial for targeting)
• organization_num_employees_ranges: Employee count ranges (very restrictive)
• currently_using_any_of_technology_uids: Technologies companies use
• revenue_range: Revenue range in dollars
• latest_funding_amount_range: Latest funding round amount
• total_funding_range: Total funding amount
• q_organization_job_titles: Job titles in active postings

Example:

{
  "query": "education technology",
  "filters": {
    "organization_locations": ["Virginia", "Maryland", "Washington DC"],
    "q_organization_keyword_tags": ["edtech", "online learning", "education technology"],
    "organization_num_employees_ranges": ["11,20", "21,50", "51,100"]
  },
  "per_page": 25
}

Filter Best Practices:

• Start with location filters - They're most effective at narrowing results
• Use specific keywords - Generic terms return too many results
• Combine multiple filters - Employee ranges + location + keywords work best
• Use comma-separated employee ranges - Format as "11,20" not "11-20"
• Employee range filters are very restrictive - If you get 0 results, try broader ranges or remove employee filters
• Test filters incrementally - Start with location + keywords, then add employee ranges if needed

Enrichment Tools

apollo_enrich_person

Enrich a person's profile using email, LinkedIn URL, or name+company.

apollo_enrich_company

Enrich a company's profile using domain or name.

apollo_bulk_enrich_people

Bulk enrich multiple people profiles.

apollo_bulk_enrich_organizations

Bulk enrich multiple organization profiles.

Additional Tools

apollo_get_organization_job_postings

Get job postings for a specific organization.

apollo_get_complete_organization_info

Get complete information for a specific organization.

apollo_search_news_articles

Search for news articles related to companies.

Filter Reference

Company Search Filters

Filter	Type	Description	Example
organization_num_employees_ranges	array	Employee count ranges (comma-separated)	["11,20", "21,50"]
organization_locations	array	Company locations	["Virginia", "Maryland"]
organization_not_locations	array	Exclude locations	["California"]
q_organization_keyword_tags	array	Industry keywords	["edtech", "saas"]
q_organization_name	string	Company name filter	"Google"
currently_using_any_of_technology_uids	array	Technologies used	["salesforce", "aws"]
revenue_range	object	Revenue range (min/max)	{"min": 1000000, "max": 10000000}
latest_funding_amount_range	object	Latest funding range	{"min": 5000000, "max": 50000000}
total_funding_range	object	Total funding range	{"min": 10000000, "max": 100000000}

People Search Filters

Filter	Type	Description	Example
locations	array	Person locations	["California", "New York"]
seniority	array	Seniority levels	["C-Level", "VP"]
departments	array	Departments	["Engineering", "Sales"]
titles	array	Job titles	["CEO", "CTO"]

Claude Desktop Integration

This MCP server has been thoroughly tested and works seamlessly with Claude Desktop. All tests pass and the MCP protocol is fully implemented. The server includes 9 comprehensive tools covering all major Apollo.io API endpoints.

Optimized for Claude Desktop: Responses are simplified and optimized for Claude Desktop compatibility, reducing response size by up to 94% while preserving all essential information.

Testing

Run all tests:

npm test

Run CLI integration test:

node test-cli.js

Test specific filters:

node test-filters.js

Test MCP Inspector integration:

node test-inspector.js

Test with MCP Inspector (Visual Testing Tool)

The MCP Inspector provides a visual interface for testing and debugging MCP servers.

Setup Inspector:

# Install dependencies and setup inspector
npm install
./setup-inspector.sh

The setup script will automatically configure the MCP Inspector with your API key from the .env file.

MCP Inspector Configuration

The inspector uses this configuration (automatically set up by the script):

{
  "mcpServers": {
    "apollo": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "APOLLO_API_KEY": "your-api-key-here",
        "APOLLO_BASE_URL": "https://api.apollo.io/api/v1"
      }
    }
  }
}

Run Inspector (UI Mode):

npm run inspector

This opens a web interface at http://localhost:6274 where you can:

• Browse all available tools with their documentation
• Test tools with form-based parameter input
• View real-time responses and errors
• Explore the MCP protocol implementation

Run Inspector (CLI Mode):

# List all available tools
npm run inspector:cli -- --method tools/list

# Test company search
npm run inspector:cli -- --method tools/call --tool-name apollo_search_companies --tool-arg query='education technology' --tool-arg per_page=5

# Test with filters
npm run inspector:cli -- --method tools/call --tool-name apollo_search_companies --tool-arg query='edtech' --tool-arg 'filters={"organization_locations":["Virginia"],"q_organization_keyword_tags":["edtech"]}' --tool-arg per_page=3

Inspector Features:

• Visual Tool Testing: Form-based interface for all tools
• Real-time Response Viewing: See API responses as they come in
• Error Debugging: Visual error messages and stack traces
• Protocol Inspection: View the underlying MCP protocol messages
• Documentation Display: See all tool descriptions and parameter schemas

Environment Setup

The API key setup is covered in the Claude Desktop Setup section above. For reference:

• For npx/npm users: Set environment variables in your Claude Desktop MCP configuration
• For source users: Create a .env file in the project directory with your API key

Troubleshooting

Common Issues

1. "Unauthorized" errors: Check your APOLLO_API_KEY in the .env file or environment variables
2. "Rate limited" errors: You've hit Apollo's API rate limits. Check your Apollo API usage dashboard for current limits
3. Large result sets: Use more specific filters to narrow results
4. Empty company results: Try different filter combinations or check API limits
5. API access denied: Some endpoints require specific API key permissions. Ensure your key has access to the endpoints you're trying to use

Filter Best Practices

1. Start with location filters - They're most effective at narrowing results
2. Use specific keywords - Generic terms return too many results
3. Combine multiple filters - Employee ranges + location + keywords work best
4. Use comma-separated employee ranges - Format as "11,20" not "11-20"
5. Employee range filters are very restrictive - If you get 0 results, try broader ranges or remove employee filters
6. Test filters incrementally - Start with location + keywords, then add employee ranges if needed

API References

• Apollo.io API Documentation
• Model Context Protocol
• Claude Desktop MCP Setup

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Releasing

This project uses semantic versioning and automated publishing. See RELEASING.md for detailed instructions.

Quick release commands:

npm run release:patch  # Bug fixes
npm run release:minor  # New features
npm run release:major  # Breaking changes

License

This project is licensed under the MIT License - see the LICENSE file for details.