# Apollo.io MCP Server

MCP server for the Apollo.io sales engagement platform, providing comprehensive tools for managing contacts, accounts, sequences, emails, tasks, and opportunities.

## Features

- **Contacts Management** - Search, create, update, and manage sales contacts
- **Accounts/Organizations** - Track and manage target companies
- **Email Sequences** - Automate outreach campaigns
- **Email Communications** - Send and track emails
- **Task Management** - Create and track follow-up actions
- **Opportunity Tracking** - Manage deals through your sales pipeline

## Installation

```bash
npm install
npm run build
```

## Configuration

Set your Apollo.io API key as an environment variable:

```bash
export APOLLO_API_KEY="your_api_key_here"
```

## Usage

Run the server:

```bash
npm start
# or
node dist/index.js
```

## Available Tools (26 total)

### Contacts (6 tools)
- `list_contacts` - Browse contact database with pagination
- `get_contact` - Retrieve detailed contact information
- `search_contacts` - Advanced contact search with filters
- `create_contact` - Add new contacts
- `update_contact` - Modify contact details
- `delete_contact` - Remove contacts

### Accounts (5 tools)
- `list_accounts` - Browse organization database
- `get_account` - Get detailed company information
- `search_accounts` - Advanced company search with filters
- `create_account` - Add new companies
- `update_account` - Modify company details

### Sequences (5 tools)
- `list_sequences` - View all email sequences
- `get_sequence` - Get sequence details and steps
- `create_sequence` - Create new outreach campaigns
- `add_contacts_to_sequence` - Enroll contacts in sequences
- `remove_contacts_from_sequence` - Unenroll contacts

### Emails (4 tools)
- `send_email` - Send one-off emails
- `list_email_accounts` - View connected email accounts
- `list_email_threads` - Browse email conversations
- `get_email_thread` - View full email thread

### Tasks (3 tools)
- `list_tasks` - View to-do items
- `create_task` - Schedule follow-up actions
- `update_task` - Modify or complete tasks

### Opportunities (3 tools)
- `list_opportunities` - View sales pipeline
- `create_opportunity` - Create new deals
- `update_opportunity` - Update deal status and details

## API Coverage Manifest

**Total Apollo.io API Endpoints:** ~150+  
**Implemented in this server:** 26  
**Coverage:** ~17%

### Covered Areas:
- ✅ Core contact management
- ✅ Account/organization management
- ✅ Email sequence automation
- ✅ Email sending and threads
- ✅ Task management
- ✅ Opportunity/deal tracking

### Not Yet Implemented:
- ⏳ Advanced analytics and reporting
- ⏳ Team and user management
- ⏳ Custom fields management
- ⏳ Labels and stages CRUD
- ⏳ Data enrichment endpoints
- ⏳ Webhook configuration
- ⏳ Import/export bulk operations
- ⏳ Call logging and recordings
- ⏳ Meeting scheduling
- ⏳ Email templates
- ⏳ Saved searches
- ⏳ Activity logging

## Architecture

```
apollo/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── client/
│   │   └── apollo-client.ts    # API client with rate limiting
│   ├── tools/
│   │   ├── contacts.ts         # Contact tools
│   │   ├── accounts.ts         # Account tools
│   │   ├── sequences.ts        # Sequence tools
│   │   ├── emails.ts           # Email tools
│   │   ├── tasks.ts            # Task tools
│   │   └── opportunities.ts    # Opportunity tools
│   └── types/
│       └── index.ts            # TypeScript interfaces
├── package.json
├── tsconfig.json
└── README.md
```

## Rate Limiting

The client implements automatic rate limiting:
- Max 5 concurrent requests
- Minimum 200ms between requests
- Automatic retry on 429 responses

## Error Handling

The server provides detailed error messages for:
- Authentication failures (401)
- Permission issues (403)
- Resource not found (404)
- Validation errors (422)
- Rate limit exceeded (429)
- Server errors (500+)

## License

MIT