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

472 lines
15 KiB
Markdown
Raw Blame History

# 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.*
Reference in New Issue View Git Blame Copy Permalink