AI Tools

Roaspy MCP Server

Connect your AI tools to Roaspy using the Model Context Protocol. Ask about revenue, ROAS, leads, campaigns and contacts in plain English.

70 tools - Streamable HTTP

Open in ChatGPT Open in Claude

The Model Context Protocol (MCP) is an open standard that lets AI assistants like Claude, Cursor and ChatGPT securely connect to external data sources. The Roaspy MCP server exposes your Roaspy analytics and CRM data as a set of tools the assistant can call on your behalf, so you can simply ask, "How are my Meta ads doing this week, with campaign names?" and get a real answer.

Installation

The server speaks the Streamable HTTP transport. Point any MCP-compatible client at:

https://mcp.roaspy.com/mcp

Claude Desktop & Cursor

Add this to your MCP configuration file:

{
  "mcpServers": {
    "roaspy": {
      "type": "http",
      "url": "https://mcp.roaspy.com/mcp"
    }
  }
}

Claude.ai (web)

Open Settings -> Connectors.
Click Add custom connector.
Paste https://mcp.roaspy.com/mcp and save.

Authentication

The server is multi-tenant. Each chat connects with its own credentials, so the same server safely serves many Roaspy accounts. Authenticate once per session:

Call connectAccount with your Roaspy API key and business ID (looks like bus_xxxx).
Credentials are held for the duration of the session, and every other tool then works automatically.
Call disconnectAccount to clear them.

Shortcut: You can paste your credentials right into a normal prompt, e.g. "How are my Meta ads doing the last 7 days, with campaign names? API: <key> Business ID: bus_xxxx" and the assistant will call connectAccount for you, then answer.

Analytics & stats

Tool	Description
`getDashboardStats`	Source of truth for totals. Revenue, cost, ROAS, total and unique sales, leads, AOV, LTV and daily time-series for a date range. Matches the Roaspy dashboard exactly.
`getCostRevenue`	Total cost vs. revenue plus a daily chart series for a date range.
`getFunnelAnalytics`	Performance analytics for a specific funnel over a date range.

AI runs ads (Meta)

Create and launch real Meta (Facebook/Instagram) ad campaigns, grounded in what has actually converted for your business. Everything is created PAUSED - going live is always a separate, explicit updateAdStatus(ACTIVE) step that starts real spend. Budgets are in minor units (cents): $50 = 5000, and any budget above the configured cap requires an explicit override.

The flow: ask "build me an ad from what's working" and the assistant will call getWinningPatterns first, then build createCampaign -> createAdSet -> createAdCreative -> createAd (or duplicateWinner in one shot). It shows you the IDs and budget, and only goes live once you confirm.

Tool	Description
`getWinningPatterns`	Start here. Top-performing campaigns and audiences by real revenue, conversion rate and average order value - the data the assistant bases new creative, targeting and budget on.
`getCreativesReport`	Which specific creatives/assets drove the best revenue and ROAS, so new creative can be modelled on the top performers.
`listMetaAdAccounts`	List the Meta ad accounts the token can manage. Call first to pick the ad account id.
`createCampaign`	Create a PAUSED campaign shell (objective, special ad categories).
`createAdSet`	Create a PAUSED ad set: audience targeting, budget (cents), optimization goal, schedule.
`createAdCreative`	Create the ad creative - the copy + media (object story spec).
`createAd`	Bind a creative to an ad set as a PAUSED ad. Last step of the chain.
`duplicateWinner`	One shot: build a full PAUSED campaign -> ad set -> creative -> ad from a winning pattern.
`updateAdStatus`	The go-live switch. Set a campaign/ad set/ad to ACTIVE, PAUSED or ARCHIVED. ACTIVE starts real spend.
`updateBudget`	Change the daily/lifetime budget on an ad set or CBO campaign (cents; capped unless overridden).
`updateEntity`	Update arbitrary fields (name, targeting, bid) on an existing campaign, ad set or ad.
`getAdEntities`	List existing campaigns, ad sets or ads on an account.
`getAdInsights`	Read live spend, delivery and ROAS for an account, campaign, ad set or ad - to verify a launch worked.

Media & creatives

Tool	Description
`uploadAdImage`	Give it an image link. Downloads the image and uploads it, returning a reusable `image_hash`.
`uploadAdVideo`	Give it a video link. Meta fetches the video from the URL and returns a `video_id`.
`createImageAdCreative`	Build a single-image link-ad creative in one call (message, headline, link, CTA, image).
`getAdImages` / `getAdVideos`	List media already uploaded to the account.
`getAdCreatives` / `getCreativeAds`	List creatives, and the ads that use a given creative.
`getAdPreview`	Render a preview of a creative/ad in a placement (Feed, Story, Reels) to show before launch.

Pages & Instagram

Tool	Description
`getUserPages`	Facebook Pages you can advertise with (and their linked IG accounts) - source of the `page_id`.
`getPagesForBusiness`	Pages owned by a Meta Business Manager.
`getIgAccounts` / `getIgMedia`	Instagram Business Accounts on an ad account, and recent media on one.
`boostIgPost`	Turn an existing organic Instagram post into a boosted ad (paused, budget-capped).
`adsLibrarySearch`	Search the public Meta Ad Library for competitive/creative research.

Custom audiences

Tool	Description
`getCustomAudiences` / `getCustomAudience`	List audiences on an account, or inspect one (size, status, subtype).
`getCustomAudienceAdSets`	Which ad sets currently target a given audience.
`createCustomAudience`	Create a customer-file, website, lookalike, app, or engagement audience.
`updateCustomAudience` / `updateCustomAudienceUsers`	Edit an audience, or add/remove members (personal data is hashed before upload).
`deleteCustomAudience`	Delete a custom audience.

Campaigns

Tool	Description
`getCampaignBreakdown`	Real Meta campaign names with leads and revenue per campaign. Defaults to the last 30 days, so it naturally lists your active campaigns. Resolves true names from contact journeys (the report fields are blank).
`getSalesReportByCampaigns`	Sales report pre-filtered to the campaigns tab, for cross-referencing campaign IDs.

Reports

Tool	Description
`getSalesReport`	Row-level attributed purchases for a date range. Supports a `tab` (platforms, ad-accounts, campaigns, ad-sets, ads). Not a total count; use `getDashboardStats` for totals.
`getLeadsReport`	Row-level attributed leads, same tab options.
`getBookingsReport`	Row-level attributed bookings, same tab options.
`getReportStats`	High-level summary statistics for the business.

Contacts

Tool	Description
`listContacts`	List contacts (up to 300/page) with search and pagination. Includes `firstSource`/`lastSource` (the ad-set/audience name).
`getContact`	Full details for a single contact.
`getContactJourney`	Full marketing journey. The `clicked` events carry the real `CAMPAIGN:` name in their note.
`getContactPurchases`	All purchases made by a contact.
`createContact`	Create a new contact.
`updateContactStatus`	Update a contact's status.

Funnels & products

Tool	Description
`listFunnels`	List all funnels for the business.
`listFunnelViews`	List all funnel views.
`listProducts`	List all products.
`listProductsByTags`	List products filtered by tags.

Purchases

Tool	Description
`createPurchase`	Record a new purchase for a contact.
`refundPurchase`	Refund an existing purchase.

Tracking links

Tool	Description
`listTrackingLinks`	List all tracking links.
`createTrackingLink`	Create a tracking link.
`updateTrackingLink`	Update a tracking link.
`deleteTrackingLink`	Delete a tracking link.

Custom metrics

Tool	Description
`listCustomMetrics`	List all custom metrics.
`createCustomMetric`	Create a custom metric from a formula.
`updateCustomMetric`	Update a custom metric.
`deleteCustomMetric`	Delete a custom metric.

Business & integrations

Tool	Description
`getBusiness`	Full details for the connected business.
`updateBusiness`	Update business settings (name, timezone, currency).
`listIntegrations`	List connected platform integrations.
`getIntegration`	Details for a specific integration (e.g. meta, stripe).
`listConversions`	List raw conversion events for a date range.

Tips & gotchas

`getDashboardStats`	Use this for any total (revenue, sales, leads, ROAS). `getSalesReport` only returns individually-attributed purchases and will undercount.
`getCampaignBreakdown`	Use this for campaign names. The report endpoints return empty campaign-name fields for most accounts.
firstSource	On a contact this is the ad-set / audience name, not the campaign name. The campaign name lives in the journey note.

Security

Treat your Roaspy API key like a password. A few good practices:

Only connect the MCP server in AI clients you trust.
Credentials are scoped to a single session and are never persisted to disk by this server.
Be cautious with prompts that mix untrusted content (e.g. pasted emails) with tool access. Prompt injection is a real risk for any MCP server.
Use disconnectAccount when you're done, or rotate the key in Roaspy if it may have been exposed.