check_token_statusLABSCO SUMMARY
Every write lands paused, and every activation is a separate, preflighted step.
That single rule is what makes an ads API safe to hand to an agent: creation, activation and rollback are different corridors with their own checks, and a delete against a live object is downgraded to a pause rather than executed. Budget increases above the configured percentage and any activation stop for confirmation, so nothing starts spending without a person saying so.
What it is
A Meta Marketing API server built as a supervised operating layer rather than a thin wrapper: reads for accounts, campaigns, ad sets, ads, insights and catalogs, plus a write corridor that creates everything paused and runs validators before touching the API.
What you get
- check_token_status, get_ad_accounts, get_account_info, get_account_pages, get_instagram_identities, discover_all_accounts — account health and identity discovery
- get_campaigns, get_campaign_details, get_adsets, get_adset_details, get_ads, get_ad_details — the object tree, read-only
- get_insights — performance normalised per objective, so an ecommerce account reports purchases and ROAS while a lead-gen account reports leads and CPL
- get_pixel_info, get_pixel_events, get_event_stats, send_test_event, run_tracking_diagnostic — pixel and conversion tracking diagnostics
- get_catalog_info, get_catalog_products, get_product_sets, validate_catalog_connections — catalog and dynamic-ads checks
- list_custom_audiences, search_interests, search_behaviors, search_geo_locations — targeting research
- create_campaign, create_adset, create_ad_from_manifest, update_campaign, update_adset, update_ad — the paused-only write corridor, with ABO/CBO rules enforced before the call
- upload_video_asset, upload_video_resumable, poll_video_processing, create_multi_asset_ad — creative upload and multi-asset ad assembly
- build_activation_pack and execute_activation_pack — preflight every object, then flip status parent-first
- build_rollback_pack and execute_rollback_pack — undo children-first, with deletes on active objects downgraded to pauses
Requirements
A Meta Marketing API access token in META_ACCESS_TOKEN (a system user token is recommended); META_APP_SECRET and META_APP_ID are optional and used for appsecret_proof. VAULT_PATH points at a marketing vault directory when you use the client-intelligence features. Installed with uv sync and launched as a Python module. By the README's count the public repository ships 57 tools under MIT and a separate premium bundle adds 41 more; its docs name 84 of the tools.
Setup effort
Build from source
USE CASES
01
Working out why an account is underperforming
Pull the campaign and ad set tree, then read insights normalised for that account's objective.
02
Checking tracking before blaming the creative
Inspect the pixel, its recent events and event stats, then run the tracking diagnostic.
03
Building a launch without launching it
Create the campaign, ad set and ads from a manifest — all paused — with ABO/CBO and naming rules enforced before each write.
04
Going live under review
Build the activation pack, read the preflight results, then execute it parent-first.
05
Undoing a bad launch
Assemble a rollback pack and run it children-first, with destructive steps downgraded to pauses.
06
Finding an audience to test
Search interests, behaviours and geo locations, and list the custom audiences already on the account.
84 tools
Listed in project docs. Your client may show a different list.
get_ad_accountsget_account_infoget_account_pagesget_instagram_identitiesdiscover_all_accountsget_campaignsget_campaign_detailsget_adsetsget_adset_detailsget_adsget_ad_detailsget_insightsget_ad_creativesget_creative_detailsget_pixel_infoget_pixel_eventsget_event_statssend_test_eventrun_tracking_diagnosticget_catalog_infoget_catalog_productsget_product_setsvalidate_catalog_connectionslist_custom_audiencessearch_interestssearch_behaviorssearch_geo_locationscreate_campaignupdate_campaigncreate_adsetupdate_adsetcreate_ad_from_manifestupdate_adupload_video_assetpoll_video_processingupload_video_resumablebulk_rename_objectsdelete_campaign_structurediagnose_pixel_on_siteresolve_page_identitygenerate_namescreate_multi_asset_adread_client_vaultgenerate_copy_from_vaultvalidate_ad_copyrun_greek_qarun_full_diagnosticfix_ad_copyenable_product_extensionsoptimize_accountaudit_all_accountsrun_optimization_cyclecreate_launch_planbuild_execution_packexecute_paused_launchbuild_mutation_packexecute_mutation_packbuild_activation_packexecute_activation_packbuild_rollback_packexecute_rollback_packbuild_review_queuelist_review_queueresolve_review_itemrecord_outcome_snapshotexpire_stale_queue_itemsbuild_operator_digestrun_scheduled_review_cycleevaluate_execution_outcomeupdate_policy_memoryget_policy_memorybuild_learning_digestrun_learning_cyclebuild_experiment_planevaluate_experimentrotate_creative_setrun_budget_governorpromote_experiment_winnerget_experiment_registryrun_scaling_cycleselect_conceptsgenerate_ad_copy_chaingenerate_auto_copyBEFORE YOU INSTALL
What to know first
Tools you get
84 tools named in the project's documentation.
Requires
META_ACCESS_TOKEN in your environment
Optional
- META_APP_SECRET in your environment
- META_APP_ID in your environment
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
You clone and build this one yourself.
Server setup
TERMINAL
git clone https://github.com/brandu-mos/konquest-meta-ads-mcp
cd konquest-meta-ads-mcp
uv sync
cp .env.example .envMCP Clients
Claude Code
CLAUDE CODE · JSON
{
"mcpServers": {
"meta-ads": {
"command": "uv",
"args": [
"--directory",
"<YOUR_PATH_TO_KONQUEST_META_ADS_MCP>",
"run",
"python",
"-m",
"meta_ads_mcp"
],
"env": {
"META_ACCESS_TOKEN": "<YOUR_META_ACCESS_TOKEN>",
"VAULT_PATH": "<YOUR_VAULT_PATH>"
}
}
}
}The configuration on this page does not set META_APP_SECRET and META_APP_ID; the project's instructions put them in a .env file. To supply them without depending on where the server looks for that file, use the block's "env" section.
