# Keap MCP Server

A comprehensive Model Context Protocol (MCP) server for Keap (formerly Infusionsoft) - providing AI-powered access to contact management, sales pipeline, marketing automation, e-commerce, and more.

## 🚀 Features

- **111 MCP Tools** across 14 categories
- **20 React Apps** with dark theme UI matching Keap brand
- Full OAuth 2.0 PKCE authentication flow
- Type-safe API client with comprehensive error handling
- Real-time data synchronization
- Webhook support for automation

## 📦 Installation

```bash
npm install @mcpengine/keap
```

## 🔧 Configuration

Create a `.env` file:

```env
KEAP_CLIENT_ID=your_client_id
KEAP_CLIENT_SECRET=your_client_secret
KEAP_REDIRECT_URI=http://localhost:3000/callback
KEAP_ACCESS_TOKEN=your_access_token
KEAP_REFRESH_TOKEN=your_refresh_token
```

## 🛠️ MCP Tools (111 Total)

### Contacts (19 tools)
Core contact management and CRM functionality.

- `keap_create_contact` - Create a new contact with email, name, phone, address, tags, custom fields
- `keap_get_contact` - Retrieve a contact by ID with all details
- `keap_update_contact` - Update an existing contact
- `keap_delete_contact` - Delete a contact permanently
- `keap_list_contacts` - List contacts with pagination and filtering
- `keap_search_contacts` - Search contacts by email, name, phone
- `keap_merge_contacts` - Merge duplicate contacts
- `keap_apply_tag_to_contact` - Apply a tag to a contact
- `keap_remove_tag_from_contact` - Remove a tag from a contact
- `keap_get_contact_tags` - Get all tags applied to a contact
- `keap_get_contact_emails` - Get email addresses for a contact
- `keap_create_contact_email` - Add a new email address to a contact
- `keap_delete_contact_email` - Remove an email address from a contact
- `keap_get_contact_credit_cards` - Get saved credit cards for a contact
- `keap_create_contact_credit_card` - Add a credit card to a contact
- `keap_get_contact_custom_fields` - Get custom field values for a contact
- `keap_update_contact_custom_field` - Update a custom field value
- `keap_list_contact_notes` - List all notes for a contact
- `keap_get_contact_model` - Get the contact data model schema

### E-Commerce (15 tools)
Product catalog, orders, transactions, and subscriptions.

- `keap_create_product` - Create a new product in the catalog
- `keap_get_product` - Get product details by ID
- `keap_update_product` - Update product information
- `keap_delete_product` - Delete a product
- `keap_list_products` - List all products with filtering
- `keap_create_order` - Create a new order for a contact
- `keap_get_order` - Get order details by ID
- `keap_delete_order` - Delete an order
- `keap_list_orders` - List orders with filtering
- `keap_list_order_transactions` - Get all transactions for an order
- `keap_get_transaction` - Get transaction details
- `keap_list_transactions` - List all transactions
- `keap_create_subscription` - Create a recurring subscription
- `keap_get_subscription` - Get subscription details
- `keap_list_subscriptions` - List all subscriptions

### Opportunities (9 tools)
Sales pipeline and opportunity management.

- `keap_create_opportunity` - Create a new sales opportunity
- `keap_get_opportunity` - Get opportunity details
- `keap_update_opportunity` - Update opportunity information
- `keap_delete_opportunity` - Delete an opportunity
- `keap_list_opportunities` - List opportunities with filtering
- `keap_list_opportunity_stage_pipeline` - Get all pipeline stages
- `keap_get_opportunity_stage_pipeline` - Get details for a specific stage
- `keap_update_opportunity_stage` - Move opportunity to different stage
- `keap_get_opportunity_model` - Get opportunity data model schema

### Affiliates (9 tools)
Affiliate program management and tracking.

- `keap_create_affiliate` - Create a new affiliate account
- `keap_get_affiliate` - Get affiliate details
- `keap_list_affiliates` - List all affiliates
- `keap_get_affiliate_clawbacks` - Get commission clawbacks for an affiliate
- `keap_get_affiliate_commissions` - Get commissions earned
- `keap_get_affiliate_payments` - Get payment history
- `keap_get_affiliate_redirect_links` - Get tracking links
- `keap_get_affiliate_summary` - Get affiliate performance summary
- `keap_list_commissions` - List all commissions

### Tasks (8 tools)
Task and activity management.

- `keap_create_task` - Create a new task
- `keap_get_task` - Get task details
- `keap_update_task` - Update task information
- `keap_delete_task` - Delete a task
- `keap_list_tasks` - List tasks with filtering
- `keap_search_tasks` - Search tasks by title or description
- `keap_complete_task` - Mark a task as completed
- `keap_get_task_model` - Get task data model schema

### Campaigns (7 tools)
Marketing campaign and sequence management.

- `keap_list_campaigns` - List all campaigns
- `keap_get_campaign` - Get campaign details
- `keap_add_contact_to_campaign` - Add a contact to a campaign
- `keap_remove_contact_from_campaign` - Remove a contact from a campaign
- `keap_get_campaign_sequences` - Get all sequences in a campaign
- `keap_add_contact_to_sequence` - Add contact to a specific sequence
- `keap_remove_contact_from_sequence` - Remove contact from sequence

### Emails (7 tools)
Email sending, templates, and opt-in management.

- `keap_send_email` - Send an email to contacts
- `keap_get_email` - Get email details
- `keap_list_emails` - List sent emails
- `keap_create_email_template` - Create a new email template
- `keap_list_email_templates` - List all email templates
- `keap_opt_in_contact` - Opt-in a contact for email marketing
- `keap_opt_out_contact` - Opt-out a contact from emails

### Appointments (6 tools)
Appointment scheduling and calendar management.

- `keap_create_appointment` - Create a new appointment
- `keap_get_appointment` - Get appointment details
- `keap_update_appointment` - Update appointment information
- `keap_delete_appointment` - Delete an appointment
- `keap_list_appointments` - List appointments with filtering
- `keap_get_appointment_model` - Get appointment data model schema

### Automations (6 tools)
Webhook and automation configuration.

- `keap_create_hook` - Create a new webhook
- `keap_list_hooks` - List all webhooks
- `keap_delete_hook` - Delete a webhook
- `keap_verify_hook` - Verify webhook configuration
- `keap_update_hook` - Update webhook settings
- `keap_list_hook_event_types` - Get available webhook event types

### Notes (6 tools)
Contact and opportunity notes.

- `keap_create_note` - Create a new note
- `keap_get_note` - Get note details
- `keap_update_note` - Update note content
- `keap_delete_note` - Delete a note
- `keap_list_notes` - List notes with filtering
- `keap_get_note_model` - Get note data model schema

### Companies (5 tools)
Company/organization management.

- `keap_create_company` - Create a new company
- `keap_get_company` - Get company details
- `keap_update_company` - Update company information
- `keap_list_companies` - List companies with filtering
- `keap_get_company_contacts` - Get all contacts for a company

### Settings (5 tools)
Account settings and configuration.

- `keap_get_account_profile` - Get account profile information
- `keap_update_account_profile` - Update account settings
- `keap_list_users` - List all users in the account
- `keap_get_application_configuration` - Get app configuration
- `keap_list_custom_fields` - List all custom field definitions

### Tags (5 tools)
Tag and category management.

- `keap_create_tag` - Create a new tag
- `keap_get_tag` - Get tag details
- `keap_list_tags` - List all tags
- `keap_create_tag_category` - Create a tag category
- `keap_list_tag_categories` - List all tag categories

### Files (4 tools)
File upload and management.

- `keap_upload_file` - Upload a file
- `keap_get_file` - Get file details and download URL
- `keap_delete_file` - Delete a file
- `keap_list_files` - List all uploaded files

## 🎨 React Apps (20 Total)

All apps feature dark theme styling with Keap's orange/amber brand accents and VSCode-style UI.

### Core Apps

1. **Contact Dashboard** (`src/ui/react-app/src/apps/contact-dashboard/`)
   - Overview of contact metrics and recent contacts
   - Quick search and filter functionality
   - Contact creation and editing

2. **Contact Detail** (`src/ui/react-app/src/apps/contact-detail/`)
   - Full contact profile with all fields
   - Tag management
   - Email and phone history
   - Custom field editor

3. **Contact Grid** (`src/ui/react-app/src/apps/contact-grid/`)
   - Sortable, filterable contact list
   - Bulk actions (tag, delete, export)
   - Advanced search

4. **Deal Detail** (`src/ui/react-app/src/apps/deal-detail/`)
   - Opportunity/deal full details
   - Stage progression tracking
   - Activity timeline

5. **Pipeline Kanban** (`src/ui/react-app/src/apps/pipeline-kanban/`)
   - Drag-and-drop deal pipeline
   - Stage-based organization
   - Deal value summaries per stage

### Campaign & Marketing

6. **Campaign Dashboard** (`src/ui/react-app/src/apps/campaign-dashboard/`)
   - Campaign performance metrics
   - Active campaigns list
   - Contact enrollment stats

7. **Campaign Detail** (`src/ui/react-app/src/apps/campaign-detail/`)
   - Campaign sequence viewer
   - Contact progress tracking
   - Enrollment/removal management

8. **Email Composer** (`src/ui/react-app/src/apps/email-composer/`)
   - Rich text email editor
   - Template selector
   - Merge field insertion
   - Send to contacts or lists

9. **Automation Builder** (`src/ui/react-app/src/apps/automation-builder/`)
   - Webhook management
   - Event type configuration
   - Automation triggers

### Calendar & Tasks

10. **Appointment Calendar** (`src/ui/react-app/src/apps/appointment-calendar/`)
    - Calendar view of appointments
    - Create/edit appointments
    - Contact association

11. **Task Manager** (`src/ui/react-app/src/apps/task-manager/`)
    - Task list with filtering
    - Task creation and assignment
    - Completion tracking

### E-Commerce

12. **Order Dashboard** (`src/ui/react-app/src/apps/order-dashboard/`)
    - Order overview and metrics
    - Recent orders list
    - Revenue summaries

13. **Order Detail** (`src/ui/react-app/src/apps/order-detail/`)
    - Full order information
    - Transaction history
    - Payment status

14. **Product Catalog** (`src/ui/react-app/src/apps/product-catalog/`)
    - Product list with images
    - Product creation and editing
    - Pricing and inventory management

15. **Subscription Manager** (`src/ui/react-app/src/apps/subscription-manager/`)
    - Active subscriptions list
    - Subscription creation
    - Billing cycle tracking

### Organization & Settings

16. **Tag Manager** (`src/ui/react-app/src/apps/tag-manager/`)
    - Tag list and creation
    - Category management
    - Tag application stats

17. **Analytics Dashboard** (`src/ui/react-app/src/apps/analytics-dashboard/`)
    - Business metrics overview
    - Contact growth charts
    - Revenue analytics

18. **Affiliate Dashboard** (`src/ui/react-app/src/apps/affiliate-dashboard/`)
    - Affiliate performance
    - Commission tracking
    - Payment history

19. **File Browser** (`src/ui/react-app/src/apps/file-browser/`)
    - Uploaded files list
    - File upload interface
    - Download and delete actions

20. **Settings Panel** (`src/ui/react-app/src/apps/settings-panel/`)
    - Account profile
    - User management
    - Custom field configuration

## 🏗️ Architecture

```
servers/keap/
├── src/
│   ├── clients/
│   │   └── keap.ts          # OAuth 2.0 client with auto-refresh
│   ├── tools/               # 14 tool files, 111 tools total
│   │   ├── affiliates-tools.ts
│   │   ├── appointments-tools.ts
│   │   ├── automations-tools.ts
│   │   ├── campaigns-tools.ts
│   │   ├── companies-tools.ts
│   │   ├── contacts-tools.ts
│   │   ├── ecommerce-tools.ts
│   │   ├── emails-tools.ts
│   │   ├── files-tools.ts
│   │   ├── notes-tools.ts
│   │   ├── opportunities-tools.ts
│   │   ├── settings-tools.ts
│   │   ├── tags-tools.ts
│   │   └── tasks-tools.ts
│   ├── types/
│   │   ├── keap.ts          # Type definitions
│   │   └── index.ts
│   ├── ui/
│   │   └── react-app/
│   │       ├── src/
│   │       │   ├── apps/    # 20 React applications
│   │       │   ├── hooks/   # Shared React hooks
│   │       │   └── styles/  # Dark theme CSS
│   │       ├── package.json
│   │       ├── tsconfig.json
│   │       └── build-all.js
│   ├── server.ts            # MCP server implementation
│   └── main.ts              # Entry point
├── dist/                    # Compiled output
├── package.json
├── tsconfig.json
└── README.md
```

## 🎯 Usage

### As MCP Server

Add to your MCP client configuration:

```json
{
  "mcpServers": {
    "keap": {
      "command": "npx",
      "args": ["-y", "@mcpengine/keap"],
      "env": {
        "KEAP_CLIENT_ID": "your_client_id",
        "KEAP_CLIENT_SECRET": "your_client_secret",
        "KEAP_ACCESS_TOKEN": "your_access_token",
        "KEAP_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

### Building React Apps

```bash
cd src/ui/react-app
npm install
npm run build
```

Individual app builds are output to `dist/{app-name}/`.

## 🔐 Authentication

The server uses OAuth 2.0 PKCE flow:

1. Set `KEAP_CLIENT_ID` and `KEAP_CLIENT_SECRET` in `.env`
2. Run the OAuth flow to get initial tokens
3. Tokens are auto-refreshed when expired
4. Refresh token is persisted for long-term access

## 📊 Data Models

All tools that create or update resources include a corresponding `get_*_model` tool that returns the schema, validation rules, and field definitions.

Example:
```typescript
// Get contact model to understand required fields
const model = await callTool('keap_get_contact_model');

// Create contact with proper fields
const contact = await callTool('keap_create_contact', {
  given_name: 'John',
  family_name: 'Doe',
  email: 'john@example.com',
  opt_in_reason: 'Website signup'
});
```

## 🚦 Rate Limits

Keap API has rate limits:
- 150 requests per second per account
- Daily request quotas based on plan

The client includes automatic retry with exponential backoff for rate limit errors.

## 🧪 Testing

```bash
npm test
```

## 📝 Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build TypeScript
npm run build

# Type check
npx tsc --noEmit
```

## 🤝 Contributing

Contributions welcome! Please ensure:
- All TypeScript code type-checks without errors
- React apps maintain dark theme consistency
- New tools include proper input schemas and descriptions
- README is updated for new functionality

## 📄 License

MIT

## 🔗 Links

- [Keap API Documentation](https://developer.keap.com/docs/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [MCPEngine GitHub](https://github.com/BusyBee3333/mcpengine)

---

**Built with ❤️ by MCPEngine**

*Keap is a registered trademark of Keap Inc. This is an unofficial community project.*