jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpengine/servers/keap
History

README.md

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

npm install @mcpengine/keap

🔧 Configuration

Create a .env file:

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

  1. Campaign Dashboard (src/ui/react-app/src/apps/campaign-dashboard/)

    • Campaign performance metrics
    • Active campaigns list
    • Contact enrollment stats

  2. Campaign Detail (src/ui/react-app/src/apps/campaign-detail/)

    • Campaign sequence viewer
    • Contact progress tracking
    • Enrollment/removal management

  3. Email Composer (src/ui/react-app/src/apps/email-composer/)

    • Rich text email editor
    • Template selector
    • Merge field insertion
    • Send to contacts or lists

  4. Automation Builder (src/ui/react-app/src/apps/automation-builder/)

    • Webhook management
    • Event type configuration
    • Automation triggers

Calendar & Tasks

  1. Appointment Calendar (src/ui/react-app/src/apps/appointment-calendar/)

    • Calendar view of appointments
    • Create/edit appointments
    • Contact association

  2. Task Manager (src/ui/react-app/src/apps/task-manager/)

    • Task list with filtering
    • Task creation and assignment
    • Completion tracking

E-Commerce

  1. Order Dashboard (src/ui/react-app/src/apps/order-dashboard/)

    • Order overview and metrics
    • Recent orders list
    • Revenue summaries

  2. Order Detail (src/ui/react-app/src/apps/order-detail/)

    • Full order information
    • Transaction history
    • Payment status

  3. Product Catalog (src/ui/react-app/src/apps/product-catalog/)

    • Product list with images
    • Product creation and editing
    • Pricing and inventory management

  4. Subscription Manager (src/ui/react-app/src/apps/subscription-manager/)

    • Active subscriptions list
    • Subscription creation
    • Billing cycle tracking

Organization & Settings

  1. Tag Manager (src/ui/react-app/src/apps/tag-manager/)

    • Tag list and creation
    • Category management
    • Tag application stats

  2. Analytics Dashboard (src/ui/react-app/src/apps/analytics-dashboard/)

    • Business metrics overview
    • Contact growth charts
    • Revenue analytics

  3. Affiliate Dashboard (src/ui/react-app/src/apps/affiliate-dashboard/)

    • Affiliate performance
    • Commission tracking
    • Payment history

  4. File Browser (src/ui/react-app/src/apps/file-browser/)

    • Uploaded files list
    • File upload interface
    • Download and delete actions

  5. 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:

{
  "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

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:

// 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

npm test

📝 Development

# 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

Built with ❤️ by MCPEngine

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