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
Add this skill
npx mdskills install thevgergroup/apollo-io-mcpComprehensive MCP server with excellent tool descriptions and detailed filter documentation
1# Apollo.io MCP Server & CLI2345A Model Context Protocol (MCP) server and command-line interface for Apollo.io. This package provides:67- **MCP Server**: Integrates Apollo.io with Claude Desktop for conversational access to B2B data8- **CLI Tool**: Command-line interface for direct API access via terminal910Both tools provide access to Apollo's comprehensive B2B database for people and company search, enrichment, and insights.1112- [Apollo.io MCP Server \& CLI](#apolloio-mcp-server--cli)13 - [Features](#features)14 - [CLI Tool](#cli-tool)15 - [Claude Desktop Setup](#claude-desktop-setup)16 - [Step 1: Get Your Apollo API Key](#step-1-get-your-apollo-api-key)17 - [Step 2: Configure Claude Desktop](#step-2-configure-claude-desktop)18 - [Using npx (Recommended)](#using-npx-recommended)19 - [If using a Developer Installation (unlikely)](#if-using-a-developer-installation-unlikely)20 - [Step 3: Test the Integration](#step-3-test-the-integration)21 - [Manual Setup (For Developers)](#manual-setup-for-developers)22 - [Claude Desktop Configuration for Source Installation](#claude-desktop-configuration-for-source-installation)23 - [Available Tools](#available-tools)24 - [Search Tools](#search-tools)25 - [`apollo_search_people`](#apollo_search_people)26 - [`apollo_search_companies`](#apollo_search_companies)27 - [Enrichment Tools](#enrichment-tools)28 - [`apollo_enrich_person`](#apollo_enrich_person)29 - [`apollo_enrich_company`](#apollo_enrich_company)30 - [`apollo_bulk_enrich_people`](#apollo_bulk_enrich_people)31 - [`apollo_bulk_enrich_organizations`](#apollo_bulk_enrich_organizations)32 - [Additional Tools](#additional-tools)33 - [`apollo_get_organization_job_postings`](#apollo_get_organization_job_postings)34 - [`apollo_get_complete_organization_info`](#apollo_get_complete_organization_info)35 - [`apollo_search_news_articles`](#apollo_search_news_articles)36 - [Filter Reference](#filter-reference)37 - [Company Search Filters](#company-search-filters)38 - [People Search Filters](#people-search-filters)39 - [Claude Desktop Integration](#claude-desktop-integration)40 - [Testing](#testing)41 - [Run all tests:](#run-all-tests)42 - [Run CLI integration test:](#run-cli-integration-test)43 - [Test specific filters:](#test-specific-filters)44 - [Test MCP Inspector integration:](#test-mcp-inspector-integration)45 - [Test with MCP Inspector (Visual Testing Tool)](#test-with-mcp-inspector-visual-testing-tool)46 - [Setup Inspector:](#setup-inspector)47 - [MCP Inspector Configuration](#mcp-inspector-configuration)48 - [Run Inspector (UI Mode):](#run-inspector-ui-mode)49 - [Run Inspector (CLI Mode):](#run-inspector-cli-mode)50 - [Inspector Features:](#inspector-features)51 - [Environment Setup](#environment-setup)52 - [Troubleshooting](#troubleshooting)53 - [Common Issues](#common-issues)54 - [Filter Best Practices](#filter-best-practices)55 - [API References](#api-references)56 - [Contributing](#contributing)57 - [License](#license)585960## Features6162- **Apollo Org and People Search** covering all major Apollo.io API endpoints63- **Claude Desktop optimized** Simple ICP discovery64- **Advanced filtering** with Apollo.io API parameter mapping65- **CLI Tool** for command-line access to Apollo.io API66- **TypeScript SDK** for programmatic access6768## CLI Tool6970The package includes a powerful command-line interface for direct API access:7172```bash73# Install globally74npm install -g @thevgergroup/apollo-io-mcp7576# Or use with npx77npx @thevgergroup/apollo-io-mcp search-people --q "Software Engineer"7879# Examples80apollo-io-cli enrich-person --email "tim@apollo.io"81apollo-io-cli search-companies --q "technology" --organization_num_employees_ranges "51,200"82apollo-io-cli org-jobs --id "5e66b6381e05b4008c8331b8"83```8485**See [CLI.md](./CLI.md) for complete CLI documentation, examples, and usage guide.**8687## Claude Desktop Setup8889This MCP server is designed to work seamlessly with Claude Desktop. Follow these steps to get started:90919293### Step 1: Get Your Apollo API Key9495Before setting up the MCP server, you'll need an Apollo API key:96971. **Launch Apollo** and go to **Settings** > **Integrations**982. **Find the API option** and click **Connect**993. **Click "API keys"** to view or create new API keys, then click **Create new key**1004. **Name your API key** (e.g., "Claude Desktop Integration") and add a description1015. **Select the endpoints** you need access to, or toggle **"Set as master key"** for full access1026. **Click "Create API key"** and copy the key to a safe location103104> **Important**: Keep your API key secure. Anyone with access to this key can make API calls through your Apollo account.105106> **Note**: API access is dependent on your Apollo pricing plan. Check [Apollo's pricing page](https://apollo.io/pricing) for details on API limits and features available with your plan.107108For more details, see the [Apollo API Key Creation Guide](https://docs.apollo.io/docs/create-api-key).109110### Step 2: Configure Claude Desktop111112Add this configuration to your Claude Desktop MCP settings:113114#### Using npx (Recommended)115116```json117{118 "mcpServers": {119 "apollo": {120 "command": "npx",121 "args": ["@thevgergroup/apollo-io-mcp@latest"],122 "env": {123 "APOLLO_API_KEY": "your-actual-api-key-here",124 "APOLLO_BASE_URL": "https://api.apollo.io/api/v1"125 }126 }127 }128}129```130131#### If using a Developer Installation (unlikely)132133```json134{135 "mcpServers": {136 "apollo": {137 "command": "node",138 "args": ["./node_modules/@thevgergroup/apollo-io-mcp/dist/server.js"],139 "env": {140 "APOLLO_API_KEY": "your-actual-api-key-here",141 "APOLLO_BASE_URL": "https://api.apollo.io/api/v1"142 }143 }144 }145}146```147148**Replace `your-actual-api-key-here` with the API key you created in Step 1.**149150### Step 3: Test the Integration151152Once configured, restart Claude Desktop and try asking:153154- "Search for software companies in California with 50-200 employees"155- "Find C-level executives in the healthcare industry"156- "Enrich the company data for google.com"157158159160161## Manual Setup (For Developers)162163If you prefer to install from source or need to modify the code:1641651. **Clone the repository:**166```bash167git clone https://github.com/thevgergroup/apollo-io-mcp168cd apollo-io-mcp169```1701712. **Install dependencies:**172```bash173npm install174```1751763. **Set up environment variables:**177```bash178# Only if .env doesn't already exist179cp env.example .env180```1811824. **Edit `.env` and add your Apollo.io API key:**183```bash184APOLLO_API_KEY=your-actual-api-key-here185APOLLO_BASE_URL=https://api.apollo.io/api/v1186```1871885. **Build the project:**189```bash190npm run build191```192193### Claude Desktop Configuration for Source Installation194195```json196{197 "mcpServers": {198 "apollo": {199 "command": "node",200 "args": ["/path/to/apollo-io-mcp/dist/server.js"],201 "env": {202 "APOLLO_API_KEY": "your-actual-api-key-here",203 "APOLLO_BASE_URL": "https://api.apollo.io/api/v1"204 }205 }206 }207}208```209210## Available Tools211212### Search Tools213214#### `apollo_search_people`215Search 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.216217**Available Filters:**218- `locations`: Person locations (cities, states, countries)219- `seniority`: Seniority levels (e.g., `["C-Level", "VP", "Director"]`)220- `titles`: Job titles (e.g., `["CEO", "CTO", "Sales Manager"]`)221- `departments`: Departments (e.g., `["Engineering", "Sales", "Marketing"]`)222- `company_domains`: Company domains (e.g., `["google.com", "microsoft.com"]`)223- `industries`: Industries (e.g., `["Software", "Healthcare", "Finance"]`)224- `technologies`: Technologies they use (e.g., `["python", "react", "salesforce"]`)225226**Example:**227```json228{229 "query": "CEO",230 "filters": {231 "locations": ["California"],232 "seniority": ["C-Level"],233 "industries": ["Software", "SaaS"]234 },235 "per_page": 10236}237```238239#### `apollo_search_companies`240Search 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.241242**Available Filters:**243- `organization_locations`: Company locations (most effective filter)244- `organization_not_locations`: Exclude specific locations245- `q_organization_keyword_tags`: Industry keywords (crucial for targeting)246- `organization_num_employees_ranges`: Employee count ranges (very restrictive)247- `currently_using_any_of_technology_uids`: Technologies companies use248- `revenue_range`: Revenue range in dollars249- `latest_funding_amount_range`: Latest funding round amount250- `total_funding_range`: Total funding amount251- `q_organization_job_titles`: Job titles in active postings252253**Example:**254```json255{256 "query": "education technology",257 "filters": {258 "organization_locations": ["Virginia", "Maryland", "Washington DC"],259 "q_organization_keyword_tags": ["edtech", "online learning", "education technology"],260 "organization_num_employees_ranges": ["11,20", "21,50", "51,100"]261 },262 "per_page": 25263}264```265266**Filter Best Practices:**267- **Start with location filters** - They're most effective at narrowing results268- **Use specific keywords** - Generic terms return too many results269- **Combine multiple filters** - Employee ranges + location + keywords work best270- **Use comma-separated employee ranges** - Format as `"11,20"` not `"11-20"`271- **Employee range filters are very restrictive** - If you get 0 results, try broader ranges or remove employee filters272- **Test filters incrementally** - Start with location + keywords, then add employee ranges if needed273274### Enrichment Tools275276#### `apollo_enrich_person`277Enrich a person's profile using email, LinkedIn URL, or name+company.278279#### `apollo_enrich_company`280Enrich a company's profile using domain or name.281282#### `apollo_bulk_enrich_people`283Bulk enrich multiple people profiles.284285#### `apollo_bulk_enrich_organizations`286Bulk enrich multiple organization profiles.287288### Additional Tools289290#### `apollo_get_organization_job_postings`291Get job postings for a specific organization.292293#### `apollo_get_complete_organization_info`294Get complete information for a specific organization.295296#### `apollo_search_news_articles`297Search for news articles related to companies.298299## Filter Reference300301### Company Search Filters302303| Filter | Type | Description | Example |304|--------|------|-------------|---------|305| `organization_num_employees_ranges` | array | Employee count ranges (comma-separated) | `["11,20", "21,50"]` |306| `organization_locations` | array | Company locations | `["Virginia", "Maryland"]` |307| `organization_not_locations` | array | Exclude locations | `["California"]` |308| `q_organization_keyword_tags` | array | Industry keywords | `["edtech", "saas"]` |309| `q_organization_name` | string | Company name filter | `"Google"` |310| `currently_using_any_of_technology_uids` | array | Technologies used | `["salesforce", "aws"]` |311| `revenue_range` | object | Revenue range (min/max) | `{"min": 1000000, "max": 10000000}` |312| `latest_funding_amount_range` | object | Latest funding range | `{"min": 5000000, "max": 50000000}` |313| `total_funding_range` | object | Total funding range | `{"min": 10000000, "max": 100000000}` |314315### People Search Filters316317| Filter | Type | Description | Example |318|--------|------|-------------|---------|319| `locations` | array | Person locations | `["California", "New York"]` |320| `seniority` | array | Seniority levels | `["C-Level", "VP"]` |321| `departments` | array | Departments | `["Engineering", "Sales"]` |322| `titles` | array | Job titles | `["CEO", "CTO"]` |323324## Claude Desktop Integration325326This 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.327328**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.329330## Testing331332### Run all tests:333```bash334npm test335```336337### Run CLI integration test:338```bash339node test-cli.js340```341342### Test specific filters:343```bash344node test-filters.js345```346347### Test MCP Inspector integration:348```bash349node test-inspector.js350```351352### Test with MCP Inspector (Visual Testing Tool)353354The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) provides a visual interface for testing and debugging MCP servers.355356#### Setup Inspector:357```bash358# Install dependencies and setup inspector359npm install360./setup-inspector.sh361```362363The setup script will automatically configure the MCP Inspector with your API key from the `.env` file.364365#### MCP Inspector Configuration366367The inspector uses this configuration (automatically set up by the script):368369```json370{371 "mcpServers": {372 "apollo": {373 "command": "node",374 "args": ["dist/server.js"],375 "env": {376 "APOLLO_API_KEY": "your-api-key-here",377 "APOLLO_BASE_URL": "https://api.apollo.io/api/v1"378 }379 }380 }381}382```383384#### Run Inspector (UI Mode):385```bash386npm run inspector387```388This opens a web interface at `http://localhost:6274` where you can:389- Browse all available tools with their documentation390- Test tools with form-based parameter input391- View real-time responses and errors392- Explore the MCP protocol implementation393394#### Run Inspector (CLI Mode):395```bash396# List all available tools397npm run inspector:cli -- --method tools/list398399# Test company search400npm run inspector:cli -- --method tools/call --tool-name apollo_search_companies --tool-arg query='education technology' --tool-arg per_page=5401402# Test with filters403npm 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=3404```405406#### Inspector Features:407- **Visual Tool Testing**: Form-based interface for all tools408- **Real-time Response Viewing**: See API responses as they come in409- **Error Debugging**: Visual error messages and stack traces410- **Protocol Inspection**: View the underlying MCP protocol messages411- **Documentation Display**: See all tool descriptions and parameter schemas412413## Environment Setup414415The API key setup is covered in the [Claude Desktop Setup](#claude-desktop-setup) section above. For reference:416417- **For npx/npm users**: Set environment variables in your Claude Desktop MCP configuration418- **For source users**: Create a `.env` file in the project directory with your API key419420## Troubleshooting421422### Common Issues4234241. **"Unauthorized" errors**: Check your `APOLLO_API_KEY` in the `.env` file or environment variables4252. **"Rate limited" errors**: You've hit Apollo's API rate limits. Check your [Apollo API usage dashboard](https://docs.apollo.io/docs/create-api-key#track-api-usage) for current limits4263. **Large result sets**: Use more specific filters to narrow results4274. **Empty company results**: Try different filter combinations or check API limits4285. **API access denied**: Some endpoints require specific API key permissions. Ensure your key has access to the endpoints you're trying to use429430### Filter Best Practices4314321. **Start with location filters** - They're most effective at narrowing results4332. **Use specific keywords** - Generic terms return too many results4343. **Combine multiple filters** - Employee ranges + location + keywords work best4354. **Use comma-separated employee ranges** - Format as `"11,20"` not `"11-20"`4365. **Employee range filters are very restrictive** - If you get 0 results, try broader ranges or remove employee filters4376. **Test filters incrementally** - Start with location + keywords, then add employee ranges if needed438439## API References440441- [Apollo.io API Documentation](https://docs.apollo.io/reference/)442- [Model Context Protocol](https://modelcontextprotocol.io/)443- [Claude Desktop MCP Setup](https://docs.anthropic.com/en/docs/claude-desktop-mcp)444445## Contributing4464471. Fork the repository4482. Create a feature branch4493. Make your changes4504. Add tests for new functionality4515. Submit a pull request452453## Releasing454455This project uses semantic versioning and automated publishing. See [RELEASING.md](RELEASING.md) for detailed instructions.456457Quick release commands:458```bash459npm run release:patch # Bug fixes460npm run release:minor # New features461npm run release:major # Breaking changes462```463464## License465466This project is licensed under the MIT License - see the LICENSE file for details.
Full transparency — inspect the skill content before installing.