io.github.mikusnuz/meta-ads

NPM · @MIKUSNUZ/META-ADS-MCP · SCANNED AUG 3

MCP server for Meta Marketing API — Facebook & Instagram ad campaign management

Available components

+14 this week 67 67 Trust /100

Trust breakdown (6 categories)

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. How we score →

Supply Chain Security87

No malware found by supply-chain analysis.Pass
Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree.Partial
No install/post-install scripts declared.Pass
Only part of the dependency tree could be resolved (95 of 99), so this covers what we could see, not the whole tree. View diagnostics → Partial

Provenance & Transparency45

Source repository is publicly reachable at the declared URL. View diagnostics → Pass
Provenance check failed: no build-provenance attestation is published. See how to fix → View diagnostics → Fail
Clear OSI-approved license (MIT).Pass
Actively maintained (last published 112 days ago).Pass
Disclosure check failed: no security disclosure policy was found in the source repository. See how to fix → Fail

Schema Quality & AI Usability85

100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).Pass
AI-judged instruction clarity (excellent).Pass
Tool/resource definitions use about 8658 tokens (~68/item across 126 items; 123 tools + 3 resources), lean.Pass
Usage-examples check failed: none of the tools include examples. See how to fix → Fail

Stability & Change Management0

Stability not yet verified: not enough scan history yet (needs a 30-day window).Unverified

Tool Coverage100

100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
100% of tool parameters carry a description.Pass

Capabilities100

Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.Pass

Unverified: 1 category

A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

Install

Add this component to your MCP client. Where a client-specific snippet is available, pick your client below and copy it straight into your config; otherwise use the connection detail shown.

npm · @mikusnuz/meta-ads-mcp

Claude Codex opencode OpenClaw Hermes Other

# add to Claude Code

claude mcp add mikusnuz-meta-ads -- npx -y @mikusnuz/meta-ads-mcp

# add to Codex CLI

codex mcp add mikusnuz-meta-ads -- npx -y @mikusnuz/meta-ads-mcp

// opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mikusnuz-meta-ads": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@mikusnuz/meta-ads-mcp"
      ],
      "enabled": true
    }
  }
}

# add to OpenClaw

openclaw mcp add mikusnuz-meta-ads --command npx --arg -y --arg @mikusnuz/meta-ads-mcp

# ~/.hermes/config.yaml

mcp_servers:
  mikusnuz-meta-ads:
    command: "npx"
    args: ["-y", "@mikusnuz/meta-ads-mcp"]

// mcp.json

{
  "mcpServers": {
    "mikusnuz-meta-ads": {
      "command": "npx",
      "args": [
        "-y",
        "@mikusnuz/meta-ads-mcp"
      ]
    }
  }
}

Changelog

Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.

2 Aug 26 +41
- Provenance: unverified → fail ▼ security
- Install scripts: unverified → pass ▲ security
- Known CVEs: unverified → partial ▲ security
- Malware scan: unverified → pass ▲ security
- Stability: Stability not yet verified: not enough scan history yet (needs a 30-day window). security
- Security disclosure: fail → unverified ▼ functional
- License: unverified → pass ▲ functional
- Dependency health: unverified → partial ▲ functional
- Maintenance: unverified → pass ▲ functional
- MCP protocol: unverified → pass ▲ functional
- Schema quality: unverified → excellent ▲ functional
- Licence: MIT functional
31 Jul 26 −27
- We updated how we score, so this day's move reflects our rubric, not a change to the server See what changed → functional
27 Jul 26 53

First indexed and scored.

Show 2 earlier entries Hide earlier entries

Diagnostics

Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.

Captured 3 Aug 2026 · Analysed npm/@mikusnuz/[email protected]

Provenance none

Ecosystem: npm · Outcome: none

Dependencies 95 packages

95 packages in the resolved dependency tree · 95 deprecated · 29 stale.

The dependency tree was only partially resolved, so these counts may be incomplete.

MCP tools — 123 exposed · ~8,605 tokens

The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability.

Tool Tokens

add_business_user ~53

Add a user to the configured business by email. Requires META_BUSINESS_ID env var.

Input Output Examples

Name	Type	Req	Description
email	string	yes	Email address of the user to add
role	string	yes	Role for the new user

No output schema declared.

No examples provided.

add_to_block_list ~56

Add publisher URLs to an existing block list.

Input Output Examples

Name	Type	Req	Description
list_id	string	yes	Block list ID
urls	string	yes	JSON array of URLs to block (e.g. '["example.com","bad-site.com"]')

No output schema declared.

No examples provided.

add_users_to_audience ~101

Add users to a custom audience. Payload must be a JSON string containing hashed user data with a schema array defining the data types (e.g. EMAIL, PHONE, FN, LN).

Input Output Examples

Name	Type	Req	Description
audience_id	string	yes	Audience ID
payload	string	yes	JSON string: {schema: ['EMAIL','PHONE',...], data: [['hash1','hash2',...], ...]}. All PII must be SHA-256 hashed.

No output schema declared.

No examples provided.

create_ad ~109

Create a new ad. Requires name, adset_id, and creative (JSON object_story_spec). Defaults to PAUSED status.

Input Output Examples

Name	Type	Req	Description
adset_id	string	yes	Parent ad set ID
creative	string	yes	JSON string of creative spec (object_story_spec with page_id, link_data/photo_data/video_data)
name	string	yes	Ad name
status	string	—	Ad status (default PAUSED)
tracking_specs	string	—	JSON string of tracking specs array

No output schema declared.

No examples provided.

create_adset ~287

Create a new ad set. Requires name, campaign_id, budget, optimization_goal, billing_event, and targeting. Defaults to PAUSED status.

Input Output Examples

Name	Type	Req	Description
bid_strategy	string	—	Bid strategy: LOWEST_COST_WITHOUT_CAP, LOWEST_COST_WITH_BID_CAP, COST_CAP, LOWEST_COST_WITH_MIN_ROAS
billing_event	string	yes	Billing event: IMPRESSIONS, LINK_CLICKS, APP_INSTALLS, THRUPLAY
campaign_id	string	yes	Parent campaign ID
daily_budget	string	—	Daily budget in currency cents (e.g. '5000' = $50.00)
end_time	string	—	End time (ISO 8601)
lifetime_budget	string	—	Lifetime budget in currency cents
name	string	yes	Ad set name
optimization_goal	string	yes	Optimization goal: IMPRESSIONS, REACH, LINK_CLICKS, LANDING_PAGE_VIEWS, OFFSITE_CONVERSIONS, APP_INSTALLS, LEAD_GENERATION, VALUE, THRUPLAY, ENGAGED_USERS
start_time	string	—	Start time (ISO 8601)
status	string	—	Ad set status (default PAUSED)
targeting	string	yes	JSON string of targeting spec (age_min, age_max, genders, geo_locations, interests, etc.)

No output schema declared.

No examples provided.

create_async_report ~190

Create an async insight report for large data queries. Returns a report_run_id to poll with get_async_report.

Input Output Examples

Name	Type	Req	Description
breakdowns	string	—	Breakdown dimensions: age,gender,country,region,placement,device_platform
date_preset	string	—	Date preset: TODAY,YESTERDAY,LAST_7D,LAST_14D,LAST_30D,THIS_MONTH,LAST_MONTH,THIS_QUARTER,LAST_QUARTER,THIS_YEAR,LAST_YEAR
fields	string	—	Comma-separated insight fields
filtering	string	—	JSON string for filtering
level	string	—	Aggregation level: campaign, adset, ad
time_increment	string	—	Time granularity: all_days, 1, 7, monthly
time_range	string	—	JSON string {since,until} in YYYY-MM-DD format

No output schema declared.

No examples provided.

create_block_list ~32

Create a new publisher block list for the ad account.

Input Output Examples

Name	Type	Req	Description
name	string	yes	Name for the block list

No output schema declared.

No examples provided.

create_budget_schedule ~96

Create a new ad budget schedule for the ad account.

Input Output Examples

Name	Type	Req	Description
budget_value	string	yes	Budget amount in account currency cents
budget_value_type	string	yes	Budget value type (e.g. ABSOLUTE, MULTIPLIER)
time_end	string	yes	Schedule end time (ISO 8601 or Unix timestamp)
time_start	string	yes	Schedule start time (ISO 8601 or Unix timestamp)

No output schema declared.

No examples provided.

create_campaign ~176

Create a new ad campaign. Defaults to PAUSED status. Requires name and objective. Budget can be set at campaign or ad set level.

Input Output Examples

Name	Type	Req	Description
daily_budget	string	—	Daily budget in account currency cents (e.g. '5000' = $50.00)
lifetime_budget	string	—	Lifetime budget in account currency cents
name	string	yes	Campaign name
objective	string	yes	Campaign objective
special_ad_categories	string	—	JSON array of special ad categories: CREDIT, EMPLOYMENT, HOUSING, ISSUES_ELECTIONS_POLITICS
start_time	string	—	Campaign start time (ISO 8601 format)
status	string	—	Campaign status (default PAUSED)
stop_time	string	—	Campaign stop time (ISO 8601 format)

No output schema declared.

No examples provided.

create_canvas ~87

Create a new Instant Experience (Canvas) on a Facebook Page. Requires page_id and body_elements JSON array defining the canvas layout.

Input Output Examples

Name	Type	Req	Description
body_elements	string	yes	JSON array of canvas body elements (buttons, carousels, photos, videos, text, etc.)
name	string	—	Canvas name
page_id	string	yes	Facebook Page ID to create the canvas on

No output schema declared.

No examples provided.

create_catalog ~50

Create a new product catalog for the ad account.

Input Output Examples

Name	Type	Req	Description
name	string	yes	Catalog name
vertical	string	—	Catalog vertical: commerce, hotels, flights, destinations, home_listings, vehicles

No output schema declared.

No examples provided.

create_creative ~106

Create a new ad creative with object_story_spec. The spec defines the ad content (link, photo, or video) and the associated Facebook Page.

Input Output Examples

Name	Type	Req	Description
asset_feed_spec	string	—	JSON string of asset_feed_spec for dynamic creative
name	string	yes	Creative name
object_story_spec	string	yes	JSON string of object_story_spec (page_id, link_data/photo_data/video_data)
url_tags	string	—	URL tags to append to all links

No output schema declared.

No examples provided.

create_custom_audience ~105

Create a new custom audience. Subtype determines the audience source (CUSTOM, WEBSITE, APP, OFFLINE_CONVERSION, LOOKALIKE, ENGAGEMENT, etc.).

Input Output Examples

Name	Type	Req	Description
customer_file_source	string	—	Source of customer file: USER_PROVIDED_ONLY, PARTNER_PROVIDED_ONLY, BOTH_USER_AND_PARTNER_PROVIDED
description	string	—	Audience description
name	string	yes	Audience name
subtype	string	yes	Audience subtype

No output schema declared.

No examples provided.

create_dynamic_creative ~93

Create a dynamic creative with asset_feed_spec. Meta automatically combines different images, videos, titles, bodies, and CTAs to find the best performing combinations.

Input Output Examples

Name	Type	Req	Description
asset_feed_spec	string	yes	JSON string of asset_feed_spec with arrays: images (hash), videos (video_id), bodies (text), titles (text), descriptions (text), call_to_action_types
name	string	yes	Creative name

No output schema declared.

No examples provided.

create_experiment ~101

Create a new A/B test experiment (ad study).

Input Output Examples

Name	Type	Req	Description
cells	string	yes	JSON array of test cells: [{name, campaign_id}]
description	string	—	Experiment description
end_time	string	yes	End time in ISO 8601 or Unix timestamp
name	string	yes	Experiment name
start_time	string	yes	Start time in ISO 8601 or Unix timestamp
type	string	—	Study type

No output schema declared.

No examples provided.

create_feed ~63

Create a new product feed for a catalog.

Input Output Examples

Name	Type	Req	Description
catalog_id	string	yes	Product catalog ID
file_url	string	—	URL of the feed file
name	string	yes	Feed name
schedule	string	—	JSON string for feed schedule configuration

No output schema declared.

No examples provided.

create_lookalike_audience ~110

Create a lookalike audience based on an existing custom audience. Ratio (1-10) determines how closely the new audience resembles the source.

Input Output Examples

Name	Type	Req	Description
lookalike_spec	string	yes	JSON string: {country: 'US', ratio: 0.01-0.10} where ratio is the lookalike percentage (1%-10%)
name	string	yes	Lookalike audience name
origin_audience_id	string	yes	Source custom audience ID

No output schema declared.

No examples provided.

create_offline_event_set ~39

Create a new offline conversion data set.

Input Output Examples

Name	Type	Req	Description
description	string	—	Event set description
name	string	yes	Event set name

No output schema declared.

No examples provided.

create_product_set ~55

Create a new product set within a catalog.

Input Output Examples

Name	Type	Req	Description
catalog_id	string	yes	Product catalog ID
filter	string	—	JSON string of filter rules for the product set
name	string	yes	Product set name

No output schema declared.

No examples provided.

create_rf_prediction ~125

Create a new reach & frequency prediction. Provide targeting spec as JSON string, budget in cents, and scheduling info.

Input Output Examples

Name	Type	Req	Description
budget	number	yes	Budget in account currency cents
destination_id	string	yes	Destination ID (e.g. Facebook Page ID)
frequency_cap	number	yes	Maximum frequency cap per user
start_time	string	yes	Prediction start time (ISO 8601 or Unix timestamp)
stop_time	string	yes	Prediction stop time (ISO 8601 or Unix timestamp)
target_spec	string	yes	JSON string of targeting specification

No output schema declared.

No examples provided.

create_rule ~66

Create a new automated rule for the ad account.

Input Output Examples

Name	Type	Req	Description
evaluation_spec	string	yes	JSON string defining rule conditions
execution_spec	string	yes	JSON string defining rule actions
name	string	yes	Rule name
schedule_spec	string	—	JSON string defining rule schedule

No output schema declared.

No examples provided.

create_system_user ~51

Create a new system user in the configured business. Requires META_BUSINESS_ID env var.

Input Output Examples

Name	Type	Req	Description
name	string	yes	Name for the system user
role	string	yes	Role for the system user

No output schema declared.

No examples provided.

debug_token ~47

Debug an access token to inspect its properties, permissions, expiration, and validity. Requires META_APP_ID and META_APP_SECRET.

Input Output Examples

Name	Type	Req	Description
input_token	string	yes	Access token to debug/inspect

No output schema declared.

No examples provided.

delete_ad ~29

Delete an ad. This action is irreversible.

Input Output Examples

Name	Type	Req	Description
ad_id	string	yes	Ad ID to delete

No output schema declared.

No examples provided.

delete_adset ~33

Delete an ad set. This action is irreversible.

Input Output Examples

Name	Type	Req	Description
adset_id	string	yes	Ad set ID to delete

No output schema declared.

No examples provided.

delete_audience ~31

Delete a custom audience. This action is irreversible.

Input Output Examples

Name	Type	Req	Description
audience_id	string	yes	Audience ID to delete

No output schema declared.

No examples provided.

delete_block_list ~33

Delete a publisher block list. This action is irreversible.

Input Output Examples

Name	Type	Req	Description
list_id	string	yes	Block list ID to delete

No output schema declared.

No examples provided.

delete_budget_schedule ~32

Delete a budget schedule. This action is irreversible.

Input Output Examples

Name	Type	Req	Description
schedule_id	string	yes	Budget schedule ID to delete

No output schema declared.

No examples provided.

delete_campaign ~29

Delete a campaign. This action is irreversible.

Input Output Examples

Name	Type	Req	Description
campaign_id	string	yes	Campaign ID to delete

No output schema declared.

No examples provided.

delete_canvas ~32

Delete an Instant Experience (Canvas). This action is irreversible.

Input Output Examples

Name	Type	Req	Description
canvas_id	string	yes	Canvas ID to delete

No output schema declared.

No examples provided.

delete_image ~31

Delete an ad image by hash. This action is irreversible.

Input Output Examples

Name	Type	Req	Description
hash	string	yes	Image hash to delete

No output schema declared.

No examples provided.

delete_rf_prediction ~33

Delete a reach & frequency prediction. This action is irreversible.

Input Output Examples

Name	Type	Req	Description
prediction_id	string	yes	Prediction ID to delete

No output schema declared.

No examples provided.

delete_rule ~23

Delete an automated rule.

Input Output Examples

Name	Type	Req	Description
rule_id	string	yes	Rule ID

No output schema declared.

No examples provided.

delete_video ~30

Delete an ad video. This action is irreversible.

Input Output Examples

Name	Type	Req	Description
video_id	string	yes	Video ID to delete

No output schema declared.

No examples provided.

exchange_token ~48

Exchange a short-lived access token for a long-lived token. Requires META_APP_ID and META_APP_SECRET to be configured.

Input Output Examples

Name	Type	Req	Description
short_lived_token	string	yes	Short-lived access token to exchange

No output schema declared.

No examples provided.

get_account_activities ~70

Get activity log for the ad account. Shows changes made to campaigns, ad sets, ads, etc.

Input Output Examples

Name	Type	Req	Description
after	string	—	Pagination cursor for next page
fields	string	—	Comma-separated fields to return
limit	number	—	Number of results (default 25)

No output schema declared.

No examples provided.

get_account_insights ~190

Get performance insights for the ad account. Returns metrics like impressions, clicks, spend, reach, etc.

Input Output Examples

Name	Type	Req	Description
breakdowns	string	—	Breakdown dimensions: age,gender,country,region,placement,device_platform
date_preset	string	—	Date preset: TODAY,YESTERDAY,LAST_7D,LAST_14D,LAST_30D,THIS_MONTH,LAST_MONTH,THIS_QUARTER,LAST_QUARTER,THIS_YEAR,LAST_YEAR
fields	string	—	Comma-separated insight fields
filtering	string	—	JSON string for filtering
level	string	—	Aggregation level: campaign, adset, ad
time_increment	string	—	Time granularity: all_days, 1, 7, monthly
time_range	string	—	JSON string {since,until} in YYYY-MM-DD format

No output schema declared.

No examples provided.

get_ad ~40

Get details of a specific ad by ID.

Input Output Examples

Name	Type	Req	Description
ad_id	string	yes	Ad ID
fields	string	—	Comma-separated fields to return

No output schema declared.

No examples provided.

get_ad_account ~42

Get details of the configured ad account including status, balance, currency, timezone, and spend info.

Input Output Examples

Name	Type	Req	Description
fields	string	—	Comma-separated fields to return

No output schema declared.

No examples provided.

get_ad_insights ~187

Get performance insights for a specific ad.

Input Output Examples

Name	Type	Req	Description
ad_id	string	yes	Ad ID
breakdowns	string	—	Breakdown dimensions: age,gender,country,region,placement,device_platform
date_preset	string	—	Date preset: TODAY,YESTERDAY,LAST_7D,LAST_14D,LAST_30D,THIS_MONTH,LAST_MONTH,THIS_QUARTER,LAST_QUARTER,THIS_YEAR,LAST_YEAR
fields	string	—	Comma-separated insight fields
filtering	string	—	JSON string for filtering
level	string	—	Aggregation level: campaign, adset, ad
time_increment	string	—	Time granularity: all_days, 1, 7, monthly
time_range	string	—	JSON string {since,until} in YYYY-MM-DD format

No output schema declared.

No examples provided.

get_ad_preview ~72

Get a preview of an ad in a specific format. Returns HTML iframe for rendering.

Input Output Examples

Name	Type	Req	Description
ad_format	string	yes	Ad format: DESKTOP_FEED_STANDARD, MOBILE_FEED_STANDARD, INSTAGRAM_STANDARD, INSTAGRAM_STORY, RIGHT_COLUMN_STANDARD, etc.
ad_id	string	yes	Ad ID

No output schema declared.

No examples provided.

get_adset ~44

Get details of a specific ad set by ID.

Input Output Examples

Name	Type	Req	Description
adset_id	string	yes	Ad set ID
fields	string	—	Comma-separated fields to return

No output schema declared.

No examples provided.

get_adset_ads ~71

Get all ads belonging to a specific ad set.

Input Output Examples

Name	Type	Req	Description
adset_id	string	yes	Ad set ID
after	string	—	Pagination cursor for next page
fields	string	—	Comma-separated fields to return
limit	number	—	Number of results (default 25)

No output schema declared.

No examples provided.

get_adset_insights ~191

Get performance insights for a specific ad set.

Input Output Examples

Name	Type	Req	Description
adset_id	string	yes	Ad Set ID
breakdowns	string	—	Breakdown dimensions: age,gender,country,region,placement,device_platform
date_preset	string	—	Date preset: TODAY,YESTERDAY,LAST_7D,LAST_14D,LAST_30D,THIS_MONTH,LAST_MONTH,THIS_QUARTER,LAST_QUARTER,THIS_YEAR,LAST_YEAR
fields	string	—	Comma-separated insight fields
filtering	string	—	JSON string for filtering
level	string	—	Aggregation level: campaign, adset, ad
time_increment	string	—	Time granularity: all_days, 1, 7, monthly
time_range	string	—	JSON string {since,until} in YYYY-MM-DD format

No output schema declared.

No examples provided.

get_adset_leads ~78

Get leads generated by a specific ad set. Requires leads_retrieval permission.

Input Output Examples

Name	Type	Req	Description
adset_id	string	yes	Ad set ID
after	string	—	Pagination cursor for next page
fields	string	—	Comma-separated fields to return
limit	number	—	Number of results (default 25)

No output schema declared.

No examples provided.

get_async_report ~49

Check status and retrieve results of an async insight report.

Input Output Examples

Name	Type	Req	Description
fields	string	—	Comma-separated fields to return
report_run_id	string	yes	Report run ID from create_async_report

No output schema declared.

No examples provided.

get_audience ~42

Get details of a specific custom audience by ID.

Input Output Examples

Name	Type	Req	Description
audience_id	string	yes	Audience ID
fields	string	—	Comma-separated fields to return

No output schema declared.

No examples provided.

get_business ~40

Get details of a specific business by ID.

Input Output Examples

Name	Type	Req	Description
business_id	string	yes	Business ID
fields	string	—	Comma-separated fields to return

No output schema declared.

No examples provided.

get_campaign ~40

Get details of a specific campaign by ID.

Input Output Examples

Name	Type	Req	Description
campaign_id	string	yes	Campaign ID
fields	string	—	Comma-separated fields to return

No output schema declared.

No examples provided.

get_campaign_ads ~67

Get all ads belonging to a specific campaign.

Input Output Examples

Name	Type	Req	Description
after	string	—	Pagination cursor for next page
campaign_id	string	yes	Campaign ID
fields	string	—	Comma-separated fields to return
limit	number	—	Number of results (default 25)

No output schema declared.

No examples provided.

On this page

Handy links

Scoring key

80+ high trust
60–79 medium
below 60 low

How we score

Score history · last 30 days

27 Jul 3 Aug