luna/marketingskills
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: add Composio as integration layer for OAuth-heavy marketing tools

Browse Source 
Adds Composio MCP server as an alternative integration method for tools
lacking native MCP support (HubSpot, Salesforce, Meta Ads, LinkedIn Ads,
Google Sheets, Slack, Notion, etc.). Existing CLIs and MCP servers are
unchanged — Composio is additive only.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Corey Haines
2026-03-13 15:37:59 -07:00
parent 1c32ad3dbf
commit 869321e949
5 changed files with 402 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
AGENTS.md
+5 -1
View File
@@ -22,6 +22,7 @@ marketingskills/
│ └── SKILL.md # Required skill file
├── tools/
│ ├── clis/ # Zero-dependency Node.js CLI tools (51 tools)
│ ├── composio/ # Composio integration layer (quick start + toolkit mapping)
│ ├── integrations/ # API integration guides per tool
│ └── REGISTRY.md # Tool index with capabilities
├── CONTRIBUTING.md
@@ -167,7 +168,8 @@ This repository includes a tools registry for agent-compatible marketing tools.
- **Tool discovery**: Read `tools/REGISTRY.md` to see available tools and their capabilities
- **Integration details**: See `tools/integrations/{tool}.md` for API endpoints, auth, and common operations
- **MCP-enabled tools**: ga4, stripe, mailchimp, google-ads, resend, zapier, zoominfo, clay, supermetrics, coupler, outreach, crossbeam
- **MCP-enabled tools**: ga4, stripe, mailchimp, google-ads, resend, zapier, zoominfo, clay, supermetrics, coupler, outreach, crossbeam, composio
- **Composio** (integration layer): Adds MCP access to OAuth-heavy tools without native MCP servers (HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, etc.). See `tools/integrations/composio.md`
### Registry Structure
@@ -189,6 +191,8 @@ Skills reference relevant tools for implementation. For example:
- `email-sequence` skill → customer-io, mailchimp, resend guides
- `paid-ads` skill → google-ads, meta-ads, linkedin-ads guides
For tools without native MCP servers (HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, Notion), Composio provides MCP access via a single server. See `tools/integrations/composio.md` for setup and `tools/composio/marketing-tools.md` for the full toolkit mapping.
## Checking for Updates
When using any skill from this repository:
tools/REGISTRY.md
+11
View File
@@ -85,6 +85,7 @@ Quick reference for AI agents to discover tool capabilities and integration meth
| sanity | Headless CMS | ✓ | - | ✓ | ✓ | [sanity.md](integrations/sanity.md) |
| contentful | Headless CMS | ✓ | - | ✓ | ✓ | [contentful.md](integrations/contentful.md) |
| strapi | Headless CMS | ✓ | - | ✓ | ✓ | [strapi.md](integrations/strapi.md) |
| composio | Integration Layer | ✓ | ✓ | ✓ | ✓ | [composio.md](integrations/composio.md) |
---
@@ -428,6 +429,16 @@ These tools have Model Context Protocol servers available, enabling direct agent
To use MCP tools, ensure the appropriate MCP server is configured in your environment.
### Composio Integration
[Composio](integrations/composio.md) provides managed OAuth and pre-built connectors for 500+ tools via a single MCP server. It adds MCP access to tools that don't have native MCP servers, including HubSpot, Salesforce, Meta Ads, LinkedIn Ads, Google Sheets, Slack, Notion, and more.
- **Setup**: `npx @composio/mcp@latest setup`
- **Quick start**: See [tools/composio/README.md](composio/README.md)
- **Marketing tool mapping**: See [tools/composio/marketing-tools.md](composio/marketing-tools.md)
Use Composio when you need MCP access to OAuth-heavy tools. Prefer native MCP servers (GA4, Stripe, Mailchimp, etc.) when available — they have deeper coverage.
---
## Quick Start by Use Case
tools/composio/README.md
+105
View File
@@ -0,0 +1,105 @@
# Composio Quick Start
Get MCP access to 500+ marketing tools through a single integration.
## Prerequisites
- Node.js 18+
- Claude Code installed
## Install
```bash
npx @composio/mcp@latest setup
```
Verify by running `/mcp` in Claude Code — `composio` should appear in the server list.
## Connect a Tool
When you ask the agent to use a Composio-backed tool for the first time, it will provide a Connect Link. Open the link in your browser, authorize the app, and you're set. The connection persists across sessions.
```
You: "Get my top HubSpot contacts"
Agent: "Please connect HubSpot first: https://app.composio.dev/connect/..."
# Click the link → authorize → return to Claude Code
Agent: "Here are your top contacts: ..."
```
## Usage Examples
### Pull CRM contacts
```
"Show me my 10 most recent HubSpot contacts with their deal stages"
```
### Get ad performance
```
"What's my Meta Ads spend and ROAS for the last 7 days?"
```
### Write to a spreadsheet
```
"Add a row to my 'Campaign Tracker' Google Sheet with today's LinkedIn Ads metrics"
```
### Cross-tool workflow
```
"Find Salesforce leads from this week and post a summary in Slack #new-leads"
```
## Available Marketing Tools
See [marketing-tools.md](marketing-tools.md) for the full list of Composio toolkits mapped to marketing use cases.
Key tools with new MCP access (no native MCP server in this repo):
- **HubSpot** — contacts, deals, companies, lists
- **Salesforce** — SOQL queries, leads, opportunities
- **Meta Ads** — campaigns, ad sets, insights
- **LinkedIn Ads** — campaigns, analytics
- **Google Sheets** — read, write, create spreadsheets
- **Slack** — messages, channels
- **Notion** — pages, databases
- **Klaviyo** — profiles, lists, campaigns
- **ActiveCampaign** — contacts, automations
## Troubleshooting
### "Tool not found" error
The tool may not be connected yet. Ask the agent to connect it, or run:
```bash
npx composio apps list
```
### Expired authentication
OAuth tokens expire. If a tool stops working, re-authenticate:
```bash
npx composio connections list # Find the connection
npx composio connections remove {id} # Remove it
# Then ask the agent to use the tool again to trigger re-auth
```
### Rate limit errors
Composio has its own rate limits (free: 20K calls/mo, 10 req/sec). If you hit them:
- Reduce request frequency
- Upgrade your Composio plan
- Use native CLI tools for high-volume operations
### MCP server not appearing
Re-run the setup command:
```bash
npx @composio/mcp@latest setup
```
Then restart Claude Code.
tools/composio/marketing-tools.md
+91
View File
@@ -0,0 +1,91 @@
# Composio Marketing Tools
Detailed mapping of Composio toolkits to marketing use cases. Organized by the same categories as [REGISTRY.md](../REGISTRY.md).
## CRM
| Composio Toolkit | Auth | Key Marketing Actions | Depth |
|-----------------|------|----------------------|-------|
| `HUBSPOT` | OAuth 2.0 | Get/create contacts, list deals by stage, get company info, manage lists, search contacts by property | Deep |
| `SALESFORCE` | OAuth 2.0 | Run SOQL queries, get/create leads, list opportunities, get account details, update records | Deep |
## Email & SMS
| Composio Toolkit | Auth | Key Marketing Actions | Depth |
|-----------------|------|----------------------|-------|
| `ACTIVECAMPAIGN` | API Key | Get contacts, list automations, add contacts to lists, get campaign stats | Medium |
| `KLAVIYO` | API Key | Get profiles, list segments, get campaign metrics, add to lists | Medium |
| `MAILCHIMP` | OAuth 2.0 | Get audiences, list campaigns, get campaign reports, add subscribers | Deep |
| `GMAIL` | OAuth 2.0 | Send emails, search inbox, read messages, manage labels | Deep |
## Advertising
| Composio Toolkit | Auth | Key Marketing Actions | Depth |
|-----------------|------|----------------------|-------|
| `FACEBOOKADS` | OAuth 2.0 | Get campaign insights, list ad sets, get ad performance, read audience data | Medium |
| `LINKEDIN` | OAuth 2.0 | Get campaign analytics, list campaigns, get company page stats | Medium |
| `GOOGLEADS` | OAuth 2.0 | Get campaign performance, list ad groups, keyword stats | Medium |
## Productivity & Collaboration
| Composio Toolkit | Auth | Key Marketing Actions | Depth |
|-----------------|------|----------------------|-------|
| `GOOGLESHEETS` | OAuth 2.0 | Read/write cells, create sheets, format ranges, append rows | Deep |
| `SLACK` | OAuth 2.0 | Send messages, read channels, upload files, search messages | Deep |
| `NOTION` | OAuth 2.0 | Read/create pages, query databases, update blocks, search | Deep |
| `AIRTABLE` | OAuth 2.0 | List/create/update records, query views, manage tables | Deep |
## Commerce
| Composio Toolkit | Auth | Key Marketing Actions | Depth |
|-----------------|------|----------------------|-------|
| `SHOPIFY` | OAuth 2.0 | Get products, list orders, get customer data, inventory levels | Deep |
## Analytics
| Composio Toolkit | Auth | Key Marketing Actions | Depth |
|-----------------|------|----------------------|-------|
| `GOOGLEANALYTICS` | OAuth 2.0 | Run reports, get real-time data, list properties | Medium |
## Coverage Depth Guide
- **Deep** — 20+ actions, covers most common operations, suitable for daily use
- **Medium** — 5-20 actions, covers core read operations and some writes
- **Shallow** — Under 5 actions, basic read-only access
## Coverage vs. Native Tools
This table shows where Composio adds value compared to what's already in the MarketingSkills registry:
| Tool | Native MCP | Native CLI | Composio MCP | Recommendation |
|------|:----------:|:----------:|:------------:|----------------|
| HubSpot | - | ✓ | ✓ | **Use Composio** — adds MCP access |
| Salesforce | - | ✓ | ✓ | **Use Composio** — adds MCP access |
| Meta Ads | - | ✓ | ✓ | **Use Composio** — adds MCP access |
| LinkedIn Ads | - | ✓ | ✓ | **Use Composio** — adds MCP access |
| Google Sheets | - | - | ✓ | **Use Composio** — only MCP option |
| Slack | - | - | ✓ | **Use Composio** — only MCP option |
| Notion | - | - | ✓ | **Use Composio** — only MCP option |
| Airtable | - | - | ✓ | **Use Composio** — only MCP option |
| ActiveCampaign | - | ✓ | ✓ | **Use Composio** — adds MCP access |
| Klaviyo | - | ✓ | ✓ | **Use Composio** — adds MCP access |
| Shopify | - | ✓ | ✓ | **Use Composio** — adds MCP access |
| Gmail | - | - | ✓ | **Use Composio** — only MCP option |
| GA4 | ✓ | ✓ | ✓ | **Use native** — deeper coverage |
| Stripe | ✓ | ✓ | ✓ | **Use native** — deeper coverage |
| Mailchimp | ✓ | ✓ | ✓ | **Use native** — deeper coverage |
| Google Ads | ✓ | ✓ | ✓ | **Use native** — deeper coverage |
## Toolkit Reference
Each Composio toolkit name maps to its `TOOL_NAME` identifier used in the Composio platform. When searching for available actions, use these exact names:
```bash
# List all actions for a toolkit
npx composio actions list --app HUBSPOT
# Search for specific actions
npx composio actions list --app FACEBOOKADS --search "insights"
```
For the full integration guide including setup, pricing, and limitations, see [composio.md](../integrations/composio.md).
tools/integrations/composio.md
+190
View File
@@ -0,0 +1,190 @@
# Composio
Managed OAuth and pre-built tool connectors for 500+ apps via a single MCP server. Provides agent-native access to marketing tools that lack native MCP support.
## Capabilities
| Integration | Available | Notes |
|-------------|-----------|-------|
| API | ✓ | REST API for managing connections and triggering actions |
| MCP | ✓ | Single MCP server exposes all connected tools |
| CLI | ✓ | `npx composio` for managing apps, connections, and actions |
| SDK | ✓ | TypeScript and Python SDKs |
## Authentication
- **Type**: OAuth 2.0 (per-tool, managed by Composio) or API Key
- **Setup**: `npx @composio/mcp@latest setup` to install, then authenticate each tool via Connect Link in browser
- **API Key** (optional): `COMPOSIO_API_KEY` env var for advanced/team usage
Composio handles OAuth token management, refresh, and storage for all connected tools. Individual tool auth types are listed in the Marketing Tools table below.
## When to Use Composio vs. Native Tools
Composio is an **alternative integration method**, not a replacement. Use this decision guide:
| Scenario | Use |
|----------|-----|
| Tool has native MCP server (GA4, Stripe, Mailchimp) | Native MCP server |
| Tool has CLI but no MCP (Meta Ads, LinkedIn Ads, HubSpot) | Composio for MCP access |
| OAuth-heavy tool with no CLI (Google Sheets, Slack, Notion) | Composio |
| Need deep, customized integration | Native API + CLI |
| Need quick read/write access across many tools | Composio |
| Tool not covered by Composio | Native API guide |
## Setup
### 1. Install the MCP server
```bash
npx @composio/mcp@latest setup
```
This adds the Composio MCP server to your Claude Code configuration.
### 2. Verify installation
In Claude Code, run `/mcp` to confirm `composio` appears in your MCP server list.
### 3. Authenticate a tool
When you first use a Composio-backed tool, you'll receive a Connect Link. Open it in your browser to complete OAuth. The connection persists across sessions.
```
# Example: connect HubSpot
> "Pull my top 10 HubSpot contacts"
# Agent will prompt: "Please authenticate HubSpot: [Connect Link]"
# Click link → authorize → done
```
### 4. API key (optional)
For advanced usage or team setups, set your Composio API key:
```bash
export COMPOSIO_API_KEY=your_key_here
```
## Marketing Tools Available via Composio
### New MCP Coverage
These tools have API guides in this repo but **no native MCP server**. Composio adds MCP access:
| Tool | Composio Toolkit | Auth Type | Coverage Depth |
|------|-----------------|-----------|----------------|
| HubSpot | `HUBSPOT` | OAuth 2.0 | Deep (contacts, deals, companies, lists, email) |
| Salesforce | `SALESFORCE` | OAuth 2.0 | Deep (SOQL, objects, leads, opportunities) |
| Meta Ads | `FACEBOOKADS` | OAuth 2.0 | Medium (campaigns, ad sets, insights) |
| LinkedIn Ads | `LINKEDIN` | OAuth 2.0 | Medium (campaigns, analytics, company pages) |
| Google Sheets | `GOOGLESHEETS` | OAuth 2.0 | Deep (read, write, create, format) |
| Slack | `SLACK` | OAuth 2.0 | Deep (messages, channels, files) |
| Notion | `NOTION` | OAuth 2.0 | Deep (pages, databases, blocks) |
| Airtable | `AIRTABLE` | OAuth 2.0 | Deep (records, tables, views) |
| ActiveCampaign | `ACTIVECAMPAIGN` | API Key | Medium (contacts, lists, automations) |
| Klaviyo | `KLAVIYO` | API Key | Medium (profiles, lists, campaigns) |
| Shopify | `SHOPIFY` | OAuth 2.0 | Deep (products, orders, customers) |
| Gmail | `GMAIL` | OAuth 2.0 | Deep (read, send, labels, search) |
### Alternative to Existing Tools
These tools **already have native MCP or CLI** in this repo. Composio provides an alternative path:
| Tool | Native Integration | Composio Toolkit | When to Use Composio |
|------|-------------------|-----------------|---------------------|
| Mailchimp | MCP ✓, CLI ✓ | `MAILCHIMP` | If native MCP setup fails |
| Google Ads | MCP ✓, CLI ✓ | `GOOGLEADS` | If OAuth is simpler via Composio |
| Stripe | MCP ✓, CLI ✓ | `STRIPE` | Prefer native (deeper coverage) |
| GA4 | MCP ✓, CLI ✓ | `GOOGLEANALYTICS` | Prefer native (deeper coverage) |
## Common Agent Operations
### List available tools
```bash
# Via Composio CLI
npx composio apps list
```
### Check connection status
```bash
npx composio connections list
```
### Trigger an action programmatically
```bash
POST https://backend.composio.dev/api/v1/actions/{action_id}/execute
{
"connectedAccountId": "account_xxx",
"input": {
"query": "contact email = user@example.com"
}
}
```
### Disconnect a tool
```bash
npx composio connections remove {connection_id}
```
## Example Workflows
### Pull CRM data into a spreadsheet
```
> "Get my top 20 HubSpot contacts by last activity and add them to a Google Sheet"
```
Agent uses Composio's `HUBSPOT` to fetch contacts and `GOOGLESHEETS` to write rows.
### Cross-platform ad reporting
```
> "Compare my Meta Ads and LinkedIn Ads spend this month"
```
Agent uses `FACEBOOKADS` and `LINKEDIN` toolkits to pull campaign data.
### Notify team about new leads
```
> "Get my Salesforce leads from today and post a summary in Slack #sales"
```
Agent uses `SALESFORCE` to read leads and `SLACK` to post messages.
## Limitations
- **Coverage depth varies** — some toolkits expose hundreds of actions (HubSpot, Google Sheets), others only a handful
- **No customization** — you can't modify Composio's action schemas or add custom endpoints
- **Vendor dependency** — if Composio's servers are down, all connected tools are unavailable
- **Rate limits apply** — Composio enforces its own rate limits on top of each tool's native limits
- **OAuth tokens** — managed by Composio; you don't control token refresh or storage
- **Action naming** — Composio action names may differ from native API terminology
## Pricing
| Plan | Monthly Price | API Calls | Notes |
|------|--------------|-----------|-------|
| Free | $0 | 20,000 | Good for exploration and personal use |
| Growth | $29 | 200,000 | For regular use across multiple tools |
| Business | $229 | 2,000,000 | For teams and heavy automation |
## Rate Limits
- Free tier: 20,000 calls/month, 10 req/sec
- Growth tier: 200,000 calls/month, 50 req/sec
- Business tier: 2,000,000 calls/month, 100 req/sec
## See Also
- [Quick start guide](../composio/README.md) — install, connect, and use in 5 minutes
- [Marketing tools mapping](../composio/marketing-tools.md) — detailed toolkit-to-category reference
## Relevant Skills
- analytics-tracking (cross-platform data via Composio connectors)
- email-sequence (ActiveCampaign, Klaviyo access)
- paid-ads (Meta Ads, LinkedIn Ads MCP access)
- referral-program (Shopify integration)