Keap MCP Server

Keap MCP Server

Complete Model Context Protocol server for Keap (formerly Infusionsoft) with 111 tools and 22 React apps.

Features

🛠️ Comprehensive Tool Coverage (111 tools)

• Contacts: Full CRUD, search, tagging, custom fields, bulk operations, merge, email opt status
• Companies: CRUD, search, company-contact associations
• Opportunities: Complete sales pipeline (CRUD, stages, stage moves, search, bulk operations)
• Tasks: CRUD, completion tracking, search, bulk updates
• Appointments: CRUD, scheduling, calendar integration, search
• Campaigns: CRUD, sequence management, contact additions, achievement tracking
• Tags: CRUD, category management, contact tagging/untagging, bulk operations
• Notes: CRUD, contact/opportunity associations, search
• Emails: Send transactional and marketing emails, templates, tracking, opt status
• Files: Upload, retrieve, associate with contacts/companies
• E-commerce: Products, orders, subscriptions, payments, refunds, transaction history
• Automations: Campaign builder sequences, goal tracking, link triggers
• Settings: Account info, user management, custom fields, settings configuration
• Affiliates: Program management, commissions, payouts, clawbacks, summaries

🎨 MCP Apps (22 React Apps)

1. Contact Dashboard - Contact list with metrics and search
2. Contact Detail - Comprehensive contact profile view
3. Contact Grid - Data grid with filtering and bulk actions
4. Contact Timeline - Activity timeline and interaction history
5. Company Dashboard - Company overview and metrics
6. Company Detail - Detailed company information
7. Company Grid - Companies data grid with search
8. Deal Dashboard - Sales pipeline overview
9. Deal Detail - Opportunity details and stage tracking
10. Pipeline Kanban - Visual drag-and-drop pipeline management
11. Pipeline Funnel - Conversion funnel visualization
12. Task Manager - Task list with priorities and due dates
13. Appointment Calendar - Calendar view with scheduling
14. Campaign Dashboard - Campaign performance metrics
15. Campaign Detail - Campaign sequence and analytics
16. Email Composer - Rich email composition interface
17. Tag Manager - Tag organization and bulk tagging
18. Automation Dashboard - Campaign builder overview
19. Product Catalog - E-commerce product management
20. Order Dashboard - Order tracking and fulfillment
21. Order Detail - Detailed order information
22. Revenue Dashboard - Revenue analytics and reporting

Installation

npm install @mcpengine/keap

Configuration

Environment Variables

KEAP_API_KEY=your_personal_access_token

Personal Access Token Setup

1. Log in to your Keap account
2. Navigate to Admin → Settings → Application
3. Click on API tab
4. Generate a new Personal Access Token
5. Copy the token and use it as KEAP_API_KEY

MCP Settings (Claude Desktop)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "keap": {
      "command": "npx",
      "args": ["-y", "@mcpengine/keap"],
      "env": {
        "KEAP_API_KEY": "your_personal_access_token"
      }
    }
  }
}

Usage Examples

Create a Contact

{
  "tool": "keap_create_contact",
  "arguments": {
    "given_name": "John",
    "family_name": "Doe",
    "email": "john.doe@example.com",
    "phone": "555-0123",
    "company_name": "Acme Corp",
    "job_title": "CTO",
    "tag_ids": [123, 456]
  }
}

Search Contacts

{
  "tool": "keap_search_contacts",
  "arguments": {
    "email": "john@example.com",
    "given_name": "John",
    "order": "email",
    "limit": 50
  }
}

Create an Opportunity

{
  "tool": "keap_create_opportunity",
  "arguments": {
    "title": "New Website Project",
    "contact_id": 12345,
    "stage_id": 789,
    "projected_revenue": 15000,
    "opportunity_notes": "Interested in complete redesign"
  }
}

Move Opportunity Stage

{
  "tool": "keap_move_opportunity_stage",
  "arguments": {
    "opportunity_id": 98765,
    "stage_id": 790,
    "notes": "Proposal sent, awaiting review"
  }
}

Tag Contacts

{
  "tool": "keap_apply_tags_to_contacts",
  "arguments": {
    "contact_ids": [123, 456, 789],
    "tag_ids": [10, 20]
  }
}

Send Email

{
  "tool": "keap_send_email",
  "arguments": {
    "contact_ids": [12345],
    "subject": "Welcome to our service!",
    "html_content": "<h1>Welcome!</h1><p>Thank you for joining us.</p>",
    "text_content": "Welcome! Thank you for joining us."
  }
}

Create a Product

{
  "tool": "keap_create_product",
  "arguments": {
    "product_name": "Premium Subscription",
    "product_price": 99.99,
    "product_desc": "Monthly premium access",
    "sku": "PREM-001",
    "status": 1
  }
}

Create an Order

{
  "tool": "keap_create_order",
  "arguments": {
    "contact_id": 12345,
    "order_items": [
      {
        "product_id": 456,
        "quantity": 2,
        "price": 99.99
      }
    ],
    "order_title": "Q1 Subscription"
  }
}

Tool Reference

Contact Tools (19 tools)

• keap_create_contact - Create new contact
• keap_get_contact - Get contact by ID
• keap_update_contact - Update contact details
• keap_delete_contact - Delete contact
• keap_list_contacts - List all contacts (paginated)
• keap_search_contacts - Search contacts by criteria
• keap_get_contact_emails - Get contact's email addresses
• keap_create_contact_email - Add email to contact
• keap_update_contact_email - Update email address
• keap_delete_contact_email - Remove email address
• keap_apply_tags_to_contact - Tag a single contact
• keap_remove_tags_from_contact - Remove tags from contact
• keap_get_contact_tags - List contact's tags
• keap_merge_contacts - Merge duplicate contacts
• keap_apply_tags_to_contacts - Bulk tag multiple contacts
• keap_remove_tags_from_contacts - Bulk remove tags
• keap_get_contact_opt_status - Check email opt-in status
• keap_opt_in_contact - Opt in contact for emails
• keap_opt_out_contact - Opt out contact from emails

Company Tools (5 tools)

• keap_create_company - Create new company
• keap_get_company - Get company by ID
• keap_update_company - Update company details
• keap_list_companies - List all companies (paginated)
• keap_search_companies - Search companies by criteria

Opportunity Tools (9 tools)

• keap_create_opportunity - Create new opportunity
• keap_get_opportunity - Get opportunity by ID
• keap_update_opportunity - Update opportunity details
• keap_list_opportunities - List opportunities (paginated)
• keap_search_opportunities - Search opportunities by criteria
• keap_move_opportunity_stage - Move opportunity to new stage
• keap_get_opportunity_pipeline - Get pipeline stages
• keap_bulk_update_opportunities - Update multiple opportunities
• keap_get_opportunity_stage_details - Get stage information

Task Tools (8 tools)

• keap_create_task - Create new task
• keap_get_task - Get task by ID
• keap_update_task - Update task details
• keap_delete_task - Delete task
• keap_list_tasks - List tasks (paginated)
• keap_search_tasks - Search tasks by criteria
• keap_complete_task - Mark task as complete
• keap_bulk_update_tasks - Update multiple tasks

Appointment Tools (6 tools)

• keap_create_appointment - Create new appointment
• keap_get_appointment - Get appointment by ID
• keap_update_appointment - Update appointment details
• keap_delete_appointment - Delete appointment
• keap_list_appointments - List appointments (paginated)
• keap_search_appointments - Search appointments by criteria

Campaign Tools (7 tools)

• keap_create_campaign - Create new campaign
• keap_get_campaign - Get campaign by ID
• keap_list_campaigns - List campaigns (paginated)
• keap_add_contact_to_campaign - Add contact to campaign sequence
• keap_remove_contact_from_campaign - Remove contact from campaign
• keap_get_campaign_sequence - Get campaign sequence details
• keap_get_campaign_achievements - Get campaign completion data

Tag Tools (5 tools)

• keap_create_tag - Create new tag
• keap_get_tag - Get tag by ID
• keap_list_tags - List all tags
• keap_create_tag_category - Create tag category
• keap_list_tag_categories - List tag categories

Note Tools (6 tools)

• keap_create_note - Create new note
• keap_get_note - Get note by ID
• keap_update_note - Update note content
• keap_delete_note - Delete note
• keap_list_notes - List notes (paginated)
• keap_search_notes - Search notes by criteria

Email Tools (7 tools)

• keap_send_email - Send email to contacts
• keap_create_email_template - Create email template
• keap_get_email_template - Get template by ID
• keap_list_email_templates - List email templates
• keap_send_template_email - Send templated email
• keap_get_email_stats - Get email sending statistics
• keap_check_email_deliverability - Check email configuration

File Tools (4 tools)

• keap_upload_file - Upload file to Keap
• keap_get_file - Download file by ID
• keap_list_files - List uploaded files
• keap_delete_file - Delete file

E-commerce Tools (15 tools)

• keap_create_product - Create new product
• keap_get_product - Get product by ID
• keap_update_product - Update product details
• keap_delete_product - Delete product
• keap_list_products - List products (paginated)
• keap_create_order - Create new order
• keap_get_order - Get order by ID
• keap_update_order - Update order details
• keap_list_orders - List orders (paginated)
• keap_create_subscription - Create recurring subscription
• keap_get_subscription - Get subscription by ID
• keap_cancel_subscription - Cancel subscription
• keap_create_payment - Record payment
• keap_refund_payment - Process refund
• keap_get_transaction_history - Get payment history

Automation Tools (6 tools)

• keap_create_campaign_sequence - Create automation sequence
• keap_get_campaign_sequence - Get sequence details
• keap_update_campaign_sequence - Update sequence
• keap_create_campaign_goal - Create campaign goal
• keap_get_campaign_goals - List campaign goals
• keap_trigger_link_click - Trigger link-based automation

Settings Tools (5 tools)

• keap_get_account_info - Get account information
• keap_list_users - List account users
• keap_get_user - Get user details
• keap_list_custom_fields - List custom fields
• keap_create_custom_field - Create custom field

Affiliate Tools (9 tools)

• keap_create_affiliate - Create affiliate account
• keap_get_affiliate - Get affiliate by ID
• keap_list_affiliates - List affiliates (paginated)
• keap_update_affiliate - Update affiliate details
• keap_get_affiliate_commissions - Get commission history
• keap_create_affiliate_payout - Create payout
• keap_create_affiliate_clawback - Reverse commission
• keap_get_affiliate_summary - Get performance summary
• keap_search_affiliates - Search affiliates by criteria

Architecture

src/
├── server.ts              # MCP server setup
├── main.ts                # Entry point
├── clients/
│   └── keap.ts           # Keap API client (REST API, rate limiting, error handling)
├── tools/                 # Tool definitions (14 files)
│   ├── contacts-tools.ts
│   ├── companies-tools.ts
│   ├── opportunities-tools.ts
│   ├── tasks-tools.ts
│   ├── appointments-tools.ts
│   ├── campaigns-tools.ts
│   ├── tags-tools.ts
│   ├── notes-tools.ts
│   ├── emails-tools.ts
│   ├── files-tools.ts
│   ├── ecommerce-tools.ts
│   ├── automations-tools.ts
│   ├── settings-tools.ts
│   └── affiliates-tools.ts
├── types/
│   └── index.ts          # TypeScript interfaces
└── ui/
    └── react-app/        # MCP Apps (22 apps)
        ├── contact-dashboard/
        ├── contact-detail/
        ├── contact-grid/
        ├── contact-timeline/
        ├── company-dashboard/
        ├── company-detail/
        ├── company-grid/
        ├── deal-dashboard/
        ├── deal-detail/
        ├── pipeline-kanban/
        ├── pipeline-funnel/
        ├── task-manager/
        ├── appointment-calendar/
        ├── campaign-dashboard/
        ├── campaign-detail/
        ├── email-composer/
        ├── tag-manager/
        ├── automation-dashboard/
        ├── product-catalog/
        ├── order-dashboard/
        ├── order-detail/
        └── revenue-dashboard/

API Coverage

• ✅ Contacts API (complete)
• ✅ Companies API (complete)
• ✅ Opportunities API (complete)
• ✅ Tasks API (complete)
• ✅ Appointments API (complete)
• ✅ Campaigns API (complete)
• ✅ Tags API (complete)
• ✅ Notes API (complete)
• ✅ Emails API (complete)
• ✅ Files API (complete)
• ✅ E-commerce API (complete - products, orders, subscriptions, payments)
• ✅ Automations API (campaign sequences, goals, triggers)
• ✅ Settings API (account info, users, custom fields)
• ✅ Affiliates API (complete)

Rate Limiting

The Keap API enforces rate limits:

• Burst limit: 10 requests per second
• Daily limit: 10,000 requests per day (may vary by plan)

The MCP client automatically handles rate limiting with:

• Exponential backoff on 429 responses
• Request queuing
• Automatic retry logic

Error Handling

All tools provide comprehensive error messages:

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "Error: Contact not found (ID: 12345)"
    }
  ]
}

Common error scenarios:

• Invalid authentication (401)
• Rate limit exceeded (429)
• Resource not found (404)
• Validation errors (400)
• Server errors (500)

Development

Build from source

git clone https://github.com/BusyBee3333/mcpengine
cd mcpengine/servers/keap
npm install
npm run build

Run in development mode

npm run dev

Type checking

npx tsc --noEmit

Build React apps

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

Best Practices

Contact Management

1. Use tags effectively: Organize contacts with meaningful tags for segmentation
2. Custom fields: Leverage custom fields for industry-specific data
3. Merge duplicates: Regularly use keap_merge_contacts to maintain data quality
4. Opt-in compliance: Always check opt status before sending marketing emails

Sales Pipeline

1. Consistent stage moves: Use keap_move_opportunity_stage to track progression
2. Revenue tracking: Keep projected revenue updated for accurate forecasting
3. Pipeline hygiene: Regularly review and close stale opportunities

Automation

1. Campaign sequences: Build automated follow-up sequences for lead nurturing
2. Goal tracking: Set clear goals to measure campaign effectiveness
3. Link triggers: Use link-based triggers for behavior-based automation

E-commerce

1. Product catalog: Maintain accurate SKUs and pricing
2. Order tracking: Use order IDs consistently across systems
3. Subscription management: Monitor subscription status and renewal dates
4. Payment reconciliation: Regular transaction history reviews

Keap Plans & Features

Different Keap plans provide varying API capabilities:

• Lite: Basic contact and email tools
• Pro: Full CRM, sales pipeline, and automation
• Max: E-commerce, advanced automations, affiliate management
• Max Classic: Legacy features, additional e-commerce capabilities

Ensure your plan supports the features you intend to use via the API.

Troubleshooting

Authentication Issues

# Verify your API key
curl -H "X-Keap-API-Key: YOUR_API_KEY" https://api.infusionsoft.com/crm/rest/v1/account/profile

Rate Limiting

If you encounter frequent rate limits:

1. Reduce concurrent request volume
2. Implement longer delays between operations
3. Consider upgrading your Keap plan for higher limits

Contact Not Found

Ensure contact IDs are valid: ``typescript // First search for the contact const result = await keap_search_contacts({ email: "user@example.com" }); // Then use the returned ID ``

Migration from Infusionsoft XML-RPC

If migrating from the legacy XML-RPC API:

1. Authentication: Replace legacy keys with Personal Access Tokens
2. Endpoints: Update from XML-RPC to REST API patterns
3. Data format: Convert XML structures to JSON
4. Field mappings: Review custom field IDs (may have changed)

License

MIT

Support

For issues and feature requests, please visit: https://github.com/BusyBee3333/mcpengine/issues

Related

• Keap API Documentation
• Keap Developer Portal
• Model Context Protocol
• MCPEngine Repository

Changelog

Version 1.0.0

• Initial release
• 111 tools across 14 categories
• 22 React apps for visual interfaces
• Full Keap REST API coverage
• Rate limiting and error handling
• Comprehensive TypeScript types