Poseidon

Winning Meta ads with Meta's EU reach, scripts and A/B tests. Find a competitor, see what changed.

Should I use this

Quality & Safety

A
Description quality
100%
Schema completeness
78%
Naming quality
91%
Poisoning risk
100%
Permission match
100%
Protocol compliance
100%

Based on automated analysis of tool definitions and protocol compliance.

Context Cost

~3,789Tokens (tool definitions)
~1.3 KBTypical response size
Significant attention impact (2.96% of 128k context)

This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.

Install

One-Click Install

Add this to your `claude_desktop_config.json` file:

{
  "mcpServers": {
    "poseidon": {
      "url": "https://api.askposeidon.app/mcp"
    }
  }
}

Remote endpoints

https://api.askposeidon.app/mcpstreamable-http

What it can do

Tool inventory

Tools (14)

🟒 Read-only🟑 WriteπŸ”΄ Deleteβšͺ Unknown
🟑search_winners(niche, country, format, has_script, active, ...)

Find winning e-commerce ads (Facebook / Instagram, Meta Ad Library) and show what's working. Use it FIRST when the user asks for winning ads, what's working or scaling in a niche or a country, the best hooks, the longest-running ads, or ads that reach a given age and gender. Examples: 'winning ads for weight loss in France', 'which hooks work for menopause in Germany' (has_script=true: each result carries its verbatim hook), 'longest-running video ads in Spain for bloating', 'ads launched last month with 1M+ EU reach' (started_after, min_eu_reach), 'ads that mostly reach women 45-54 in Germany' (age, gender, min_segment_share). Winner = live 21+ days (change with min_days_live). Each result: Ad Library link, shop link, format, days live, still running or stopped, versions, EU reach (Meta's total, with its read date), the country's or segment's share of Meta's breakdown, and the verbatim hook when the script is transcribed and fully in English or translated (sections_status 'served'; 'translation_pending' = no hook yet). Then call get_ad on the best ones for the full script. For medians or typical values across many ads, use get_weights instead. Values for niche, country and format: call filters (free). Coverage: e-commerce ads from Meta's Ad Library delivered in the EU and UK, read daily, with Meta's EU reach. Not covered: spend and impressions (Meta doesn't publish them for commercial ads), TikTok/Google ads. Creative types (UGC, VSL, demo…) and hook types are AI labels on part of the ads, served with their measured accuracy. Costs 5 credits (0 if nothing matches).

Input Schema

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "description": "e.g. 'weight loss', 'menopause', 'bloating', 'cellulite', 'gut health' (exact list: filters). It is the niche of the search that found the brand."
    },
    "country": {
      "type": "string",
      "description": "2-letter code where the ad reached people, e.g. FR, DE, IT, ES, BE"
    },
    "format": {
      "type": "string",
      "description": "Meta's display format: VIDEO, IMAGE, DCO (dynamic creative), DPA, CAROUSEL. For UGC, VSL, demo… use creative_type (an AI label with its measured accuracy, on part of the ads), not format."
    },
    "has_script": {
      "type": "boolean",
      "description": "true = only ads whose script is transcribed and cut into sections (use it for hooks and scripts)"
    },
    "active": {
      "type": "boolean",
      "description": "true = still running at the last read, false = stopped"
    },
    "min_days_live": {
      "type": "integer",
      "minimum": 0,
      "description": "default 21 (the winner rule); 0 = all ads"
    },
    "max_days_live": {
      "type": "integer",
      "minimum": 0
    },
    "started_after": {
      "type": "string",
      "format": "date",
      "description": "launched on or after, e.g. 2026-10-01"
    },
    "started_before": {
      "type": "string",
      "format": "date"
    },
    "min_eu_reach": {
      "type": "integer",
      "minimum": 0,
      "description": "people reached in the EU (Meta's total)"
    },
    "age": {
      "type": "string",
      "enum": [
        "13-17",
        "18-24",
        "25-34",
        "35-44",
        "45-54",
        "55-64",
        "65+"
      ],
      "description": "an age band of Meta's breakdown (with gender for a segment)"
    },
    "gender": {
      "type": "string",
      "enum": [
        "female",
        "male"
      ]
    },
    "min_country_share": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "needs country: 0.5 = the country holds at least half of the ad's breakdown (its main country)"
    },
    "min_segment_share": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "needs age or gender: minimum share of the ad's breakdown in that segment, e.g. 0.3"
    },
    "min_versions": {
      "type": "integer",
      "minimum": 0,
      "description": "Meta's count of ads sharing the creative"
    },
    "hook_type": {
      "type": "string",
      "description": "AI label of the hook: in validation, not served for now (the verbatim hook text is in every result)"
    },
    "creative_type": {
      "type": "string",
      "description": "AI label of the creative: in validation, not served for now (Meta's format is in `format`)"
    },
    "region": {
      "type": "string",
      "enum": [
        "EU"
      ],
      "description": "EU = ads with Meta's EU data; US data opens after its audit"
    },
    "sort": {
      "type": "string",
      "enum": [
        "country_share",
        "days_live",
        "eu_reach",
        "newest",
        "segment_share",
        "versions"
      ],
      "description": "default: eu_reach when a country, age or gender is given, else days_live"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "default 10"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 90,
      "description": "offset + limit at most 100: the first 100 results of a query"
    }
  },
  "additionalProperties": false
}
🟒get_ad(ad_id, formula)

One ad in full, by its Meta Ad Library id. Use it to read an ad's whole script, see how it is built, or check one ad the user names ('show me the script of ad 862034243491035', 'break down this ad'). Returns the verbatim script sentence by sentence, each labelled Hook, Problem, Agitation, Mechanism, Proof, Product, Offer, CTA…, the ad text and title, format, dates, days live, versions, EU reach history (Meta's total per read day), country and age x gender shares of Meta's breakdown, links to the Ad Library and the shop, and the source of every field. Script sections (hook, problem, CTA…) are served only when every sentence has an English version or the script is in English; otherwise script.sections_status is 'translation_pending' and the transcript comes without section labels (being translated nightly); 'withheld' = this ad's sections can't be served (older breakdown without text). Costs 2 credits.

Input Schema

{
  "type": "object",
  "properties": {
    "ad_id": {
      "type": "string",
      "description": "the Ad Library id: the digits after ?id= in facebook.com/ads/library/?id=…"
    },
    "formula": {
      "type": "string",
      "enum": [
        "v5",
        "v4",
        "v3"
      ],
      "description": "rank formula: v5 and v4 = rank-v4 (default), v3 until 20/11/2026"
    }
  },
  "required": [
    "ad_id"
  ],
  "additionalProperties": false
}
🟒find_brand(q)

Find a competitor by name or shop domain, before get_brand or brand_changes. Use it whenever the user names a brand or store ('show me Epycure's ads', 'what is Leaf running', 'gymshark.com'). Fuzzy: returns up to 10 confirmed e-commerce brands, best first, each with what matched (page name or shop domain), its page_id, shop link, and how many ads, winners and active ads Poseidon holds. No search of people's names: a page named after a person is found by its shop domain only. Free.

Input Schema

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "brand name or shop domain, e.g. 'epycure' or 'leaf-cosmetics.com'"
    }
  },
  "required": [
    "q"
  ],
  "additionalProperties": false
}
🟒brand_changes(page_id, since)

Watch a competitor: what changed for one brand since a date. Use it for 'what's new from <brand>', 'did they launch or stop ads', 'what is scaling for them this week'. Returns, each with its date and source: ads started (Meta's start date), ads stopped (Meta's stop date), ads whose version count rose, new ads relaunching a media the brand already used, and the ads whose EU reach grew most between two readings. Get the page_id with find_brand. Costs 5 credits (0 if nothing changed).

Input Schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "string",
      "description": "Meta page id (from find_brand)"
    },
    "since": {
      "type": "string",
      "format": "date",
      "description": "default: 7 days ago"
    }
  },
  "required": [
    "page_id"
  ],
  "additionalProperties": false
}
πŸ”΄watchlist_edit(add, remove)

Save competitors to watch, on your key: add or remove brands by page_id (get it with find_brand), up to 25. Use it when the user says 'watch these brands', 'add X to my competitors', 'stop watching Y'. Only confirmed e-commerce brands can be added. Returns the watchlist. Free.

Input Schema

{
  "type": "object",
  "properties": {
    "add": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "page ids to add"
    },
    "remove": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "page ids to remove"
    }
  },
  "additionalProperties": false
}
🟒get_facts(niche, region)

Weighted facts about what wins, each with its sample and its odds: e.g. 'in weight loss, EU, same brand and same launch day, video reached more people than image in 28 of 40 brands (70%, 95% interval 55-82%, p = 0.017)'. Use it when the user asks what is proven, what works better, video or image, or wants evidence rather than examples. Only facts that pass today are returned (30+ brands, p < 0.05, interval excluding 50%), with n, share, interval, p, method, read dates, caveats (always repeat them with the fact) and the commit of the code that computed them. Free.

Input Schema

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "description": "e.g. weight loss"
    },
    "region": {
      "type": "string",
      "enum": [
        "EU",
        "US"
      ]
    }
  },
  "additionalProperties": false
}
🟑watchlist_webhook(url, remove, test)

Get pushes instead of polling: set an https URL on your key and Poseidon POSTs the new changes of your watched brands (new ads, stopped ads, more versions, reused media, reach growth) about every hour, signed with HMAC-SHA256 (header Poseidon-Signature: t=…,v1=…; the secret is returned once when the URL is set), retried with backoff for about 15 hours. Each push costs what watchlist_changes costs (5 credits per brand with something new). Without arguments: shows the webhook and its recent deliveries. Free to set.

Input Schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "https URL that receives the pushes (public address)"
    },
    "remove": {
      "type": "boolean",
      "description": "true removes the webhook"
    },
    "test": {
      "type": "boolean",
      "description": "true sends a test push within a minute"
    }
  },
  "additionalProperties": false
}
βšͺwatchlist

The brands saved on your key's watchlist (page_id, name, shop, date added). Free.

Input Schema

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}
🟑watchlist_changes(since)

What changed across ALL your watched competitors since a date, in one call. Use it for 'what's new from my competitors', 'weekly competitor report'. Same content, dates and sources as brand_changes, grouped by brand; brands with no change are listed apart. Also says how many watched ads have at least two reach readings since the date (reach growth can only be shown for those). Costs 5 credits per brand that changed; 0 if none did.

Input Schema

{
  "type": "object",
  "properties": {
    "since": {
      "type": "string",
      "format": "date",
      "description": "default: 7 days ago"
    }
  },
  "additionalProperties": false
}
🟒get_brand(domain, page_id)

What one brand or shop is running on Meta. Use it when the user names a store or brand ('what is epycure.com running', 'how long do Leaf Co's ads last'). Give the shop domain (e.g. epycure.com) or the Meta page id. Returns the shop (link, platform), the brand's ads in Poseidon by format, how many are winners, the median days live (when 30+ ads), its 10 longest-running ads with reach, links and verbatim hooks, and its A/B tests with a measured outcome. Poseidon reads up to 30 ads per brand page. Costs 5 credits.

Input Schema

{
  "type": "object",
  "properties": {
    "domain": {
      "type": "string",
      "description": "the shop's website, e.g. epycure.com"
    },
    "page_id": {
      "type": "string",
      "description": "Meta page id, if known"
    }
  },
  "additionalProperties": false
}
🟒search_experiments(niche, country, format, kind, with_outcome, ...)

Brands' own A/B tests and which version won. Use it when the user asks what brands tested, which video, text or hook won, or for 'A/B test' or 'split test' results ('did shapewear brands in France test different videos with the same text, and which won?'). A test = ads of one brand launched within 14 days that share one element and differ in another: same video with different texts, same text with different videos (most tests), or same script with a different hook (rare). Each version: its ads with links, launch day, running or stopped, days live, EU reach, and the text that differs, whether the test is clean (only the tested element differs; this compares ad fields, not the video content: right 35 of 40 times in a hand check, so say it), plus a verdict: the version that reached most (with the ratio) when the gap is 2x or more; when the only signal is that one version stopped first, it says so and that this is not a confirmed outcome yet (repeat that). Only tests with a measured outcome are served (a version still running while another stopped, or 2x+ the reach). A summary covers all matching tests per kind (decided by survival, by reach, median reach ratio), shown only from 30 tests of a kind. Costs 5 credits (0 if nothing matches).

Input Schema

{
  "type": "object",
  "properties": {
    "niche": {
      "type": "string",
      "description": "as in search_winners (see filters)"
    },
    "country": {
      "type": "string",
      "description": "2-letter code: tests with an ad reaching that country"
    },
    "format": {
      "type": "string",
      "description": "Meta's display format of the ads tested, e.g. VIDEO, IMAGE"
    },
    "kind": {
      "type": "string",
      "enum": [
        "same_video_other_text",
        "same_text_other_video",
        "same_body_other_hook"
      ]
    },
    "with_outcome": {
      "type": "boolean",
      "description": "always true: only tests with a measured outcome are served"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20,
      "description": "default 10"
    },
    "offset": {
      "type": "integer",
      "minimum": 0,
      "maximum": 90,
      "description": "offset + limit at most 100: the first 100 results of a query"
    }
  },
  "additionalProperties": false
}
🟒get_weights(dimension, value, signal, niche, country, ...)

Medians and statistics across many ads (not single ads): the median days live, median EU reach or median versions of a format, niche, country or target, with the sample size. Use it FIRST for any question about a median, an average, a typical value or a comparison of formats: 'median days live of video ads in weight loss', 'do videos last longer than images', 'which format reaches more'. Each row: dimension (format, niche, country, target…), value (e.g. VIDEO), signal (days_live, eu_reach, versions, active, share_in_country, relaunches, test_survivor), sample size, median, top 10%, and when it was computed. Rows under 30 ads are never shown. A row may carry a 'caveat' (today on days_live, active and test_survivor: ads that died young are missing, so survival is overstated): always repeat it with the number. For formats, format_pair_weight adds weights from paired experiments (same brand, two formats launched the same week): reach ratio A vs B with a 95% interval over brands, shown from 30 brands, a winner only when the interval excludes x1; quote its note (a strong hint, not a controlled test). Costs 10 credits (0 if nothing is returned).

Input Schema

{
  "type": "object",
  "properties": {
    "dimension": {
      "type": "string",
      "description": "format, niche, country, target"
    },
    "value": {
      "type": "string",
      "description": "e.g. VIDEO (for format), FR (for country)"
    },
    "signal": {
      "type": "string",
      "description": "days_live, eu_reach, versions, active, share_in_country, relaunches, test_survivor"
    },
    "niche": {
      "type": "string"
    },
    "country": {
      "type": "string"
    },
    "region": {
      "type": "string",
      "description": "EU or 'not measured'"
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "formula": {
      "type": "string",
      "enum": [
        "v5",
        "v4",
        "v3"
      ],
      "description": "weight formula: v5 (default, full set on the niche-page cohort) or v4 / v3 (kept until 20/11/2026)"
    }
  },
  "additionalProperties": false
}
βšͺfilters

Free. The values Poseidon accepts, with live counts: niches, Meta formats, countries with reach data, age bands, sort orders, the winner rule and the coverage. Call it when unsure of a niche name or a country code, or when the user asks what Poseidon covers.

Input Schema

{
  "type": "object",
  "properties": {}
}
βšͺaccount

Free. Credits left (they never expire), prices per call, the last calls and credit movements. Use it when the user asks about credits, balance, usage or cost.

Input Schema

{
  "type": "object",
  "properties": {}
}

Community

Rate this Server

Evidence

Recent observations

verifiedversion not recorded14 tools