Roaspy

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.

Streamable HTTP
Beta: Roaspy MCP is in beta. Features and tools may change, and you may run into issues. If something doesn't work, contact Roaspy customer support.

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 ad attribution and analytics 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)

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

Authentication

When you add the connector, your client opens a Roaspy sign-in page. Log in with your Roaspy account - there is no API key to copy or paste.

  1. Add the connector and sign in to Roaspy when prompted.
  2. Ask your question. The assistant lists your businesses and lets you pick one (if you have only one, it asks before using it), then reuses it for the conversation.
  3. You can only access businesses your Roaspy account belongs to.
Shortcut: include your business ID in the first prompt, e.g. "How are my Meta ads doing the last 7 days, with campaign names? Business ID: bus_xxxx"

Analytics & stats

ToolDescription
roaspy_getDashboardStatsSource 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.
roaspy_getCostRevenueTotal cost vs. revenue plus a daily chart series for a date range.
roaspy_getFunnelAnalyticsPerformance analytics for a specific funnel over a date range.

AI runs ads (Meta)

Create a Meta (Facebook/Instagram) single-image ad, based on what has actually worked for your business in Roaspy. The assistant acts as an advisor: it suggests from your data, explains why, and you decide. Everything is created PAUSED. Nothing spends money until you approve publishing.

The flow (9 steps): 1. research your Roaspy data -> 2. ask which ad account, Page, goal, budget and audience -> 3. write the ad text -> 4. you approve the plan -> 5. build it, paused -> 6. show what Meta saved, with a preview link -> 7. you approve publishing -> 8. re-check everything against the plan -> 9. publish. The assistant cannot delete anything.

Budgets: how it really works

Meta tools

ToolDescription
meta_getTopDestinationUrlsStep 1. The website links your past ads send people to, ranked by how many ads use each.
meta_listAdAccountsStep 2. Your ad accounts, with their currency and status.
meta_getUserPages / meta_getPageByIdStep 2. The Facebook Pages you can advertise from.
meta_searchTargetingStep 2. Meta's ids for places, interests and languages, so the audience is never guessed.
meta_uploadAdImageStep 5. Upload the image from a public https link (jpg or png, max 10 MB).
meta_createCampaignStep 5. Create the campaign (goal), paused.
meta_createAdSetStep 5. Create the ad set (audience, daily budget, schedule), paused.
meta_createImageAdCreativeStep 5. Create the creative: Page, image, text, link and button.
meta_createAdStep 5. Create the ad, paused.
meta_getAdEntitiesSteps 6 and 8. Read what Meta actually saved, including Meta's reasons if an ad cannot run.
meta_getAdPreviewStep 6. A preview link of the ad (needs a Facebook login).
meta_updateAdStatusStep 9. Turn a campaign, ad set or ad on (ACTIVE) or off (PAUSED). ACTIVE starts real spend and only works with the budget you confirmed.

All figures (revenue, ROAS, sales) always come from Roaspy, never from Meta.

Campaigns

ToolDescription
roaspy_getCampaignBreakdownReal 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).
roaspy_getSalesReportByCampaignsSales report pre-filtered to the campaigns tab, for cross-referencing campaign IDs.

Reports

ToolDescription
roaspy_getSalesReportRow-level attributed purchases for a date range. Supports a tab (platforms, ad-accounts, campaigns, ad-sets, ads). Not a total count; use roaspy_getDashboardStats for totals.
roaspy_getLeadsReportRow-level attributed leads, same tab options.
roaspy_getBookingsReportRow-level attributed bookings, same tab options.
roaspy_getReportStatsHigh-level summary statistics for the business.

Contacts

ToolDescription
roaspy_listContactsList contacts (up to 300/page) with search and pagination. Includes firstSource/lastSource (the ad-set/audience name).
roaspy_getContactFull details for a single contact.
roaspy_getContactJourneyFull marketing journey. The clicked events carry the real CAMPAIGN: name in their note.
roaspy_getContactPurchasesAll purchases made by a contact.
roaspy_createContactCreate a new contact.
roaspy_updateContactStatusUpdate a contact's status.

Funnels & products

ToolDescription
roaspy_listFunnelsList all funnels for the business.
roaspy_listFunnelViewsList all funnel views.
roaspy_listProductsList all products.
roaspy_listProductsByTagsList products filtered by tags.

Purchases

ToolDescription
roaspy_createPurchaseRecord a new purchase for a contact.
roaspy_refundPurchaseRefund an existing purchase.

Tracking links

ToolDescription
roaspy_listTrackingLinksList all tracking links.
roaspy_createTrackingLinkCreate a tracking link.
roaspy_updateTrackingLinkUpdate a tracking link.
roaspy_deleteTrackingLinkDelete a tracking link.

Custom metrics

ToolDescription
roaspy_listCustomMetricsList all custom metrics.
roaspy_createCustomMetricCreate a custom metric from a formula.
roaspy_updateCustomMetricUpdate a custom metric.
roaspy_deleteCustomMetricDelete a custom metric.

Business & integrations

ToolDescription
roaspy_listBusinessesList the businesses your Roaspy account belongs to.
roaspy_getBusinessFull details for the connected business.
roaspy_updateBusinessUpdate business settings (name, timezone, currency).
roaspy_listIntegrationsList connected platform integrations.
roaspy_getIntegrationDetails for a specific integration (e.g. meta, stripe).
roaspy_listConversionsList raw conversion events for a date range.

Tips & gotchas

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

Security

A few good practices:

  1. Only connect the MCP server in AI clients you trust.
  2. You sign in with your Roaspy account; this server never sees or stores your password.
  3. 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.
  4. To revoke access, remove the connector from your AI client or sign out of Roaspy.