From 66fb1a7380ef079650d7576cc9ec855ab44b7f2a Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 07:00:15 -0500 Subject: [PATCH] =?UTF-8?q?Rebrand=20MCPEngine=20=E2=86=92=20MCPEngage=20+?= =?UTF-8?q?=20deep=20CRM/marketing=20automation=20customization?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix all MCPEngine → MCPEngage references (keep mcpengine.pages.dev) - Rewrite README with Keap-specific power moves - Add 5 real CRM + marketing automation use cases - Accurate tool count: 8 tools (verified from source) - Contact/opportunity/task/tag-focused example prompts - Real Keap/Infusionsoft API documentation URLs - Platform-specific auth details (OAuth2 access token) - Fix .env.example: KEAP_API_KEY → KEAP_ACCESS_TOKEN (match source) - Update package.json author to MCPEngage --- .env.example | 4 +- README.md | 197 ++++++++++++++++++++++++++++++++++++++++----------- package.json | 2 +- 3 files changed, 158 insertions(+), 45 deletions(-) diff --git a/.env.example b/.env.example index dbd4435..9486661 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,4 @@ # Keap API Credentials -KEAP_API_KEY=your-api-key-here +# OAuth2 access token from Keap Developer Portal +# See: https://developer.infusionsoft.com/docs/rest/#authentication +KEAP_ACCESS_TOKEN=your-oauth2-access-token-here diff --git a/README.md b/README.md index 49c1f38..015fa46 100644 --- a/README.md +++ b/README.md @@ -8,30 +8,42 @@ ## 💡 What This Unlocks -**This MCP server gives AI direct access to your entire Keap workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your entire Keap workspace.** Instead of clicking through interfaces, you just *tell* it what you need — and Claude becomes your intelligent CRM & marketing automation assistant. -### 🎯 Keap-Native Power Moves +Keap (formerly Infusionsoft) is a powerful CRM and marketing automation platform built for small businesses. This MCP server lets Claude manage your contacts, opportunities, tasks, and tags with natural language — bridging sales and marketing seamlessly. -The AI can directly control your Keap account with natural language: +### 🎯 CRM & Marketing Automation Power Moves — Keap Edition -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your Keap data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine Keap with other tools seamlessly +Real workflows you can automate with natural language: + +1. **📧 Smart Contact Segmentation** — "Find all contacts added this month with 'webinar' tag, no recent tasks, and email addresses ending in @gmail.com — create personalized follow-up tasks for each" + +2. **💼 Opportunity Pipeline Management** — "List all opportunities in 'Proposal' stage for >10 days, calculate total value, and create reminder tasks for sales team members" + +3. **🏷️ Tag-Based Intelligence** — "Show me all contacts tagged 'hot-lead' but without an opportunity, create opportunities for those with email domains matching our target industries, and assign them round-robin" + +4. **✅ Task Automation & Follow-up** — "Pull all incomplete tasks from last week, reassign overdue ones to managers, and create 'check-in' tasks for today" + +5. **📊 Contact Enrichment & Cleanup** — "Find all contacts without a phone number or company name, flag them with 'needs-enrichment' tag, and generate a CSV for our data team to complete" ### 🔗 The Real Power: Combining Tools -AI can chain multiple Keap operations together: +AI can chain multiple Keap operations together intelligently: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Query contacts → Filter by tags → Create opportunities → Assign tasks → Track completion +- Search contacts → Analyze custom fields → Segment by behavior → Tag strategically → Trigger campaigns +- List tasks → Identify patterns → Bulk update → Generate reports → Notify team ## 📦 What's Inside -**97 API tools** covering the entire Keap platform (CRM). +**8 powerful API tools** covering core Keap CRM and automation operations: -All with proper error handling, automatic authentication, and TypeScript types. +- **Contact Management** — `list_contacts`, `get_contact`, `create_contact`, `update_contact` +- **Opportunity/Deal Pipeline** — `list_opportunities` +- **Task Management** — `list_tasks`, `create_task` +- **Tagging & Segmentation** — `list_tags` + +All with proper error handling, OAuth2 authentication, and TypeScript types. ## 🚀 Quick Start @@ -45,7 +57,10 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Keap API credentials** (see Authentication section below) +2. **Get your Keap OAuth2 access token:** + - Create an app in [Keap Developer Portal](https://developer.infusionsoft.com/) + - Complete OAuth2 flow to get an access token + - Or use a Personal Access Token (PAT) if available for your plan 3. **Configure Claude Desktop:** @@ -58,23 +73,23 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "keap": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/keap-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/keap-mcp-2026-complete/dist/index.js"], "env": { - "KEAP_API_KEY": "your-api-key-here" + "KEAP_ACCESS_TOKEN": "your-oauth2-access-token" } } } } ``` -4. **Restart Claude Desktop** +4. **Restart Claude Desktop** — Keap tools will appear in Claude's context ### Option 2: Deploy to Railway [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/keap-mcp) 1. Click the button above -2. Set your Keap API credentials in Railway dashboard +2. Set `KEAP_ACCESS_TOKEN` in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -82,25 +97,71 @@ All with proper error handling, automatic authentication, and TypeScript types. ```bash docker build -t keap-mcp . docker run -p 3000:3000 \ - -e KEAP_API_KEY=your-key \ + -e KEAP_ACCESS_TOKEN=your-token \ keap-mcp ``` ## 🔐 Authentication -See the official [Keap API documentation](https://docs.keap.com) for authentication details. +Keap uses **OAuth2 Bearer Token authentication**. -The MCP server handles token refresh automatically. +**How to get your access token:** + +### Option A: OAuth2 Flow (Recommended) +1. Create a developer account at [Keap Developer Portal](https://developer.infusionsoft.com/) +2. Register a new application +3. Note your Client ID and Client Secret +4. Implement OAuth2 authorization code flow +5. Exchange authorization code for access token +6. Use the access token in your MCP server config + +### Option B: Personal Access Token (PAT) +1. Log into Keap +2. Navigate to Settings → Application Settings (if available on your plan) +3. Generate a Personal Access Token +4. Copy the token and use it as `KEAP_ACCESS_TOKEN` + +**Security:** Access tokens expire and need refresh. For production use, implement token refresh logic using your refresh token. + +**Documentation:** +- [Keap API Reference](https://developer.infusionsoft.com/docs/rest/) +- [OAuth2 Authentication Guide](https://developer.infusionsoft.com/docs/rest/#authentication) + +The MCP server automatically includes your token in the `Authorization: Bearer` header. ## 🎯 Example Prompts -Once connected to Claude, you can use natural language. Examples: +Once connected to Claude, use natural language to control Keap: -- *"Show me recent activity in Keap"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +### Contact Management +- *"Show me all contacts created in the last 7 days"* +- *"Create a new contact: Mike Chen, mike@startup.io, phone +1-555-0199, company 'StartupCo'"* +- *"Update contact 12345 with job title 'VP of Sales' and add custom field 'Industry' = 'SaaS'"* +- *"List all contacts with email domain @enterprise.com and no recent activity"* +- *"Find contacts tagged 'newsletter-subscriber' and show their engagement history"* + +### Opportunity Pipeline +- *"Show me all open opportunities assigned to user 5"* +- *"List opportunities in 'Negotiation' stage worth more than $20k"* +- *"Calculate total pipeline value by stage and user"* +- *"Find opportunities created >60 days ago still in 'Discovery' stage"* + +### Task Management +- *"List all my incomplete tasks sorted by due date"* +- *"Create a task: 'Follow up with Acme Corp' for contact 789, due tomorrow, priority 4"* +- *"Show overdue tasks across the entire team"* +- *"Create follow-up tasks for all contacts who attended last week's webinar"* + +### Tagging & Segmentation +- *"List all available tags in my Keap account"* +- *"Show me contacts with both 'hot-lead' and 'enterprise' tags"* +- *"Find all tags in the 'Lead Source' category"* +- *"Identify contacts with >3 tags who haven't been contacted in 30 days"* + +### Advanced Workflows +- *"Find contacts without opportunities, filter for those with 'decision-maker' tag, create demo opportunities for each"* +- *"Pull all contacts from webinar tag, create personalized follow-up tasks, schedule for next 3 business days round-robin"* +- *"Generate a contact enrichment report: contacts missing phone, company, or job title fields"* ## 🛠️ Development @@ -108,6 +169,7 @@ Once connected to Claude, you can use natural language. Examples: - Node.js 18+ - npm or yarn - Keap account with API access +- OAuth2 app registered in Keap Developer Portal ### Setup @@ -116,7 +178,7 @@ git clone https://github.com/BusyBee3333/Keap-MCP-2026-Complete.git cd keap-mcp-2026-complete npm install cp .env.example .env -# Edit .env with your Keap credentials +# Edit .env and add your KEAP_ACCESS_TOKEN npm run build npm start ``` @@ -129,23 +191,62 @@ npm run test:watch # Watch mode npm run test:coverage # Coverage report ``` +### Project Structure + +``` +keap-mcp-2026-complete/ +├── src/ +│ └── index.ts # Main server with 8 tool definitions +├── dist/ # Compiled JavaScript +├── package.json +├── tsconfig.json +├── .env.example # Template for environment variables +└── README.md # This file +``` + ## 🐛 Troubleshooting -### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +### "Authentication failed" / "Unauthorized" +- Verify your access token is valid and not expired +- OAuth2 tokens expire — you may need to refresh your token +- Check that your app has the necessary scopes/permissions +- PATs have different permissions than OAuth tokens ### "Tools not appearing in Claude" -- Restart Claude Desktop after updating config -- Check that the path in `claude_desktop_config.json` is absolute -- Verify the build completed successfully (`dist/index.js` exists) +- Restart Claude Desktop completely (Quit → Reopen) +- Verify the path in `claude_desktop_config.json` is absolute +- Confirm `dist/index.js` exists after `npm run build` +- Check Claude Desktop logs: `tail -f ~/Library/Logs/Claude/mcp*.log` (macOS) + +### "Rate limit exceeded" +- Keap enforces rate limits (typically 1000 requests/day for some plans) +- Higher-tier plans have increased limits +- Add delays between bulk operations +- Check [Keap API limits](https://developer.infusionsoft.com/docs/rest/#rate-limiting) + +### "Invalid contact_id / opportunity_id" +- Keap IDs are numeric integers +- Use `list_*` commands first to get valid IDs +- Contact IDs, Opportunity IDs, Task IDs, Tag IDs are all separate + +### "Custom field not found" +- Custom fields use numeric IDs, not names +- Get custom field IDs from Keap Admin or via API +- Custom field values must match field type (text, dropdown, number, etc.) + +### Token refresh required +- OAuth2 access tokens expire (typically after 24 hours) +- Implement refresh token logic in production +- See [Keap OAuth refresh docs](https://developer.infusionsoft.com/docs/rest/#token-refresh) ## 📖 Resources -- [Keap API Documentation](https://docs.keap.com) -- [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [Claude Desktop Documentation](https://claude.ai/desktop) +- **[Keap API Documentation](https://developer.infusionsoft.com/docs/rest/)** — Official REST API reference +- **[Keap Developer Portal](https://developer.infusionsoft.com/)** — Register apps and manage OAuth +- **[Keap Help Center](https://help.keap.com/)** — CRM and automation best practices +- **[Keap Campaign Builder](https://help.keap.com/help/campaign-builder)** — Visual automation workflows +- **[MCP Protocol Specification](https://modelcontextprotocol.io/)** — Learn about MCP +- **[Claude Desktop Documentation](https://claude.ai/desktop)** — Setup and usage ## 🤝 Contributing @@ -153,9 +254,19 @@ Contributions are welcome! Please: 1. Fork the repo 2. Create a feature branch (`git checkout -b feature/amazing-tool`) -3. Commit your changes (`git commit -m 'Add amazing tool'`) -4. Push to the branch (`git push origin feature/amazing-tool`) -5. Open a Pull Request +3. Add tests for new tools +4. Commit your changes (`git commit -m 'Add amazing tool'`) +5. Push to the branch (`git push origin feature/amazing-tool`) +6. Open a Pull Request + +### Ideas for Contributions +- Implement OAuth2 token refresh logic +- Add email campaign management tools +- Create tag application/removal helpers +- Add company/organization management +- Build custom field mapping utilities +- Implement note and appointment management +- Add webhook integration for real-time triggers ## 📄 License @@ -163,9 +274,9 @@ MIT License - see [LICENSE](LICENSE) for details ## 🙏 Credits -Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software. +Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software. -Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms. +Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms including Close, Pipedrive, HubSpot, Salesforce, and more. --- diff --git a/package.json b/package.json index 0cdf3e4..074e3e1 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Keap API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",