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

Merge pull request #178 from coreyhaines31/feature/composio-integration

Browse Source 
Add Composio as integration layer for OAuth-heavy tools
This commit is contained in:
Corey Haines
2026-03-13 17:03:53 -07:00
committed by GitHub
parent 1c32ad3dbf 869321e949
commit b970e9d8e4
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)