How to connect Meta Ads to Hermes Agent
Connect Meta Ads to Hermes Agent with ClawLink: create a Meta app, mint a system user token, paste it once, and 50 ad tools work from chat. Nothing running on your machine.

Manage Facebook and Instagram ad campaigns, creatives, and audiences. Once connected, Hermes Agent can read and act on Meta Ads from chat — pairing, token refresh, and tool wiring handled for you.
Most guides for giving Hermes Agent Meta Ads access start with registering your own OAuth app or pasting API keys into env files, then leave the token refresh and tool wiring to you. ClawLink gives Hermes a more practical Meta Ads setup: pair once in the browser and your always-on Hermes agent can act on Meta Ads for you, reading and doing real work on your behalf with no auth, token refresh, or tool wiring to build yourself.
Setup
It takes three steps to connect Hermes to Meta Ads.
- 1
Install and pair
Install the ClawLink plugin, then pair Hermes with a one-time browser approval:
hermes plugins install ClawLink-HQ/hermes-plugin --enable - 2
Connect Meta Ads
Paste your API key in the dashboard.
- 3
Use it from chat
Ask Hermes Agent: "What can you do with Meta Ads?"
Install by command
The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:
hermes plugins install ClawLink-HQ/hermes-plugin --enable
hermes clawlink begin # prints an approval link — open it and approve
hermes clawlink finish # after approving in the browser
hermes clawlink testThen connect Meta Ads in the ClawLink dashboard — paste your Meta Ads API key once.
Verify the connection by asking Hermes:
Run metaads_get_ad_accounts and show me the account ids. For the one I pick, call metaads_get_insights at campaign level for yesterday with spend, impressions, clicks, and CPC. Sort by spend and tell me which campaign moved most against the day before.
Using a different agent?
The Hermes plugin is one client of ClawLink's MCP server. Claude Code, Cursor, Codex, or any agent that can run a shell command pairs with the same ClawLink account through the CLI:
npx -y @useclawlink/cli loginlogin opens the same browser approval and stores a credential locally. Once Meta Ads is connected in the dashboard, that agent calls the same 93 Meta Ads tools over MCP. Full setup for MCP clients and shell agents: connect apps to any AI agent.
Meta Ads MCP for Hermes
Looking for a Meta Ads MCP server for Hermes Agent? ClawLink connects Meta Ads to Hermes Agent and exposes 93 Meta Ads tools your agent can call over MCP, with hosted auth and nothing to run or maintain yourself. Using OpenClaw instead? The OpenClaw Meta Ads integration works the same way.
Meta Ads is the one integration on ClawLink where you still mint a credential on Meta's side. Our hosted OAuth app is in review, so today the connect screen asks you to paste a system user access token once and ClawLink stores it server-side. The dashboard guide walks the Meta screens in order: create a small Marketing API app, put it Live, create a system user, assign the ad account and app, then generate a Never-expiring token with ads_read, ads_management, and business_management. After the paste, the 50 tools below work from Hermes chat with nothing running on your machine.
Meta Ads and Facebook are two different connections
They share a login and nothing else, which is a common source of confusion when a tool is missing.
- This page is ads only. Campaigns, ad sets, creatives, audiences, insights, and Business Manager structure. If you ask the agent to post to your Page, none of these 50 tools will do it.
- Page posting and Messenger live on the Hermes Facebook integration. That connection covers
facebook_create_post,facebook_get_page_insights,facebook_send_message, and the rest of the Page surface, and it connects through Facebook OAuth rather than a pasted token. - Instagram is a third connection. Publishing, comments, and Instagram insights are on the Hermes Instagram integration.
Connect the ones you need separately. A prompt that mixes ad metrics and Page posts needs two connections, and the agent will tell you which tool it cannot find.
What the Hermes Agent Meta Ads integration can do
93 Meta Ads tools are ready for Hermes Agent once the account is connected. The 30 below are the ones people reach for most; your agent can call all 93.
30 of 93 Meta Ads tools for Hermes
| Tool | What it does |
|---|---|
Create ad metaads_create_ad | Create a new ad within an ad set using the Meta Marketing API |
Create ad creative metaads_create_ad_creative | Create a new ad creative using the Meta Marketing API |
Create ad set metaads_create_ad_set | Create a new ad set within a campaign using the Meta Marketing API |
Create campaign metaads_create_campaign | Create a new advertising campaign using the Meta Marketing API |
Get ad accounts metaads_get_ad_accounts | Retrieve all ad account IDs accessible to the authenticated user from Meta Ads |
Get ad creative metaads_get_ad_creative | Get Ad Creative |
Get insights metaads_get_insights | Get insights data for a Meta Ads object (ad account, campaign, ad set, or ad) using the Meta Marketing API |
Get object metaads_get_object | Retrieve data for any Meta Marketing API object by its ID |
Get page accounts metaads_get_page_accounts | Retrieve permanent page access tokens for accounts managed by the user |
Get user metaads_get_user | Retrieve information about the authenticated user from Meta (Facebook) Graph API |
List ad creatives metaads_list_ad_creatives | List all ad creatives under an ad account |
List ad network analytics metaads_list_ad_network_analytics | Retrieve ad network analytics for a Meta Business using the Meta Marketing API |
Estimate ad delivery metaads_estimate_ad_delivery | Estimate monthly audience delivery for targeting and optimization settings in a Meta ad account |
Estimate targeting reach metaads_estimate_targeting_reach | Estimate the audience-size range for a Meta ad account and structured targeting specification |
Generate ad previews metaads_generate_ad_previews | Render previews for a provider-native creative specification in a Meta ad account and return |
Get ad preview metaads_get_ad_preview | Render a placement-specific preview for an existing Meta Ad or Ad Creative |
Get ad study metaads_get_ad_study | Get one Meta ad study by ID, including projected cells and timing |
Get current app metaads_get_current_app | Return selected metadata for the Meta application associated with the connected access token |
Get multiple objects metaads_get_multiple_objects | Retrieve selected fields for up to 50 distinct Meta Marketing API objects |
Get pixel event stats metaads_get_pixel_event_stats | Read recent Pixel event-count and processing statistics, optionally restricted to server events |
List activities metaads_list_activities | List activity history for a Meta ad account or ad set |
List ad account pixels metaads_list_ad_account_pixels | List the Pixels and consolidated datasets associated with an ad account so a usable data-source |
List ad account recommendations metaads_list_ad_account_recommendations | Return one page of Meta recommendations for an advertising account |
List ad images metaads_list_ad_images | List one page of image assets in a Meta ad account, optionally restricted to exact image hashes |
List ad network analytics results metaads_list_ad_network_analytics_results | Retrieve ad network analytics results for Facebook Audience Network |
List ad rule history metaads_list_ad_rule_history | Return one page of historical changes and executions for a Meta Automated Rule |
List ad studies metaads_list_ad_studies | List one page of A/B tests and other ad studies owned by a Meta business, including projected |
List ad videos metaads_list_ad_videos | List one page of video assets in a Meta ad account, optionally filtered by title, dimensions |
List ads metaads_list_ads | List a page of ads under a Meta ad account, with optional selection of returned fields |
List agencies metaads_list_agencies | Retrieve agencies associated with a Meta Business or Ad Account |
Try it: find the Meta Ads tool you need
Browse the 30 Meta Ads tools
Click any tool to see exactly what Hermes can do and copy a ready-to-use prompt.
Example prompts
Run metaads_get_ad_accounts and show me the account ids. For the one I pick, call metaads_get_insights at campaign level for yesterday with spend, impressions, clicks, and CPC. Sort by spend and tell me which campaign moved most against the day before.
How the Meta Ads tools behave
From the manifest and from what fails first in practice. The first two explain most confusing errors.
- Nothing resolves a campaign name to an id.
metaads_get_ad_accountsis the entry point, and everything else takes ids that come from a previous call. Ad account ids carry anact_prefix; campaign, ad set, and ad ids are bare numeric strings. An agent that invents one gets error 100, which reads like the object was deleted. - Creating a campaign is four objects, not one. Campaign, then ad set, then creative, then ad:
metaads_create_campaign,metaads_create_ad_set,metaads_create_ad_creative,metaads_create_ad. Each takes the parent's id. This is why "launch a campaign for me" cannot be one call, and why settingstatustoPAUSEDat each step is the safe way to draft. metaads_get_objectis the general reader. It fetches any Marketing API object by id, which is useful when a more specific tool does not exist for what you want. It is also the tool most likely to be handed a guessed id.- Insights are one tool across every level.
metaads_get_insightsworks on an ad account, campaign, ad set, or ad, depending on the id you pass. The level comes from the object, not from a separate tool. - Business-asset listing is broad. Tools such as
metaads_list_business_ad_accounts,metaads_list_owned_pages,metaads_list_system_users, andmetaads_list_clientsread Business Manager structure rather than ad performance. They are the fastest way to see what the token's identity has been assigned. metaads_upload_ad_imagecomes before a creative that uses an image. Meta wants the image hash, so the upload happens first and the creative references it.
ClawLink vs. building it yourself
The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Meta Ads working from chat.
| Manual | ClawLink | |
|---|---|---|
| Credential handling | Collect, validate, store, and rotate the Meta Ads API key yourself, then make sure every tool call uses the right account. | Users complete the hosted ClawLink setup once and the connected Meta Ads account becomes available to the agent without you building credential management. |
| Ongoing maintenance | You own refresh logic, permission debugging, environment config, and every provider-specific edge case for Meta Ads. | ClawLink handles the repetitive integration plumbing so your team can focus on the workflow instead of the infrastructure. |
| Agent usability | You still need to expose the right Meta Ads actions to the runtime in a format your agent can reliably use. | 93 tools for Meta Ads are already exposed through ClawLink, so the agent can read and act from chat immediately. |
ClawLink vs. Composio
Composio also exposes Meta Ads to AI agents. It is developer infrastructure: Python and TypeScript SDKs, an MCP server, and a catalog past 1,000 apps, aimed at teams shipping agent products. ClawLink is built for Hermes Agent users instead. You install the plugin once, connect Meta Ads in the browser, and the 93 tools above work from chat. There is no SDK and no config file, and the Meta Ads key you paste at setup is stored server-side rather than kept in your environment. Choosing between them? Read the full Composio alternatives comparison.
Troubleshooting
Hermes paired but still can't use Meta Ads
Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.
Connection succeeds but no tools appear
Reconnect Meta Ads from the dashboard, then start a fresh chat if the runtime still has the old tool catalog loaded.
"Tool schema not loaded yet" error when calling Meta Ads tools
Meta Ads tool schemas load on demand the first time a tool runs and are cached after that, so this error usually clears on its own: wait a few seconds and retry the same request. If every Meta Ads call keeps failing with it in a fresh chat, reconnect from the dashboard, and contact support if it still persists — that pattern points to a configuration problem on our side, not something you can fix by reconnecting again.
Meta Ads returns 403 or "permission denied" on one action while others work
Two usual causes. The connected account may not have access to the specific workspace, inbox, store, or project in the request — check that first. If access looks right, the agent may have sent a placeholder value (like "YOUR_ID" or an example id from documentation) instead of a real one: ask it to run a list or search tool first, then retry the action with a real id from those results. Most failures at this stage are one of these two, not ClawLink bugs.
Meta returns error_subcode 1885183 or "created by an app that is in development mode"
The connection and the creative arguments are fine. Meta will not promote an ad whose creative post was created by an app still in Development mode (Unpublished). Open developers.facebook.com/apps, select the app that minted your ClawLink token, add your company's privacy policy URL and a Category under App settings → Basic, then switch Development → Live (or Publish). No App Review is needed for your own ad accounts, and you do not need to reconnect in ClawLink. Reading and reporting keep working either way, which is why everything else on the connection looked healthy.
Ask the agent to diagnose it:
Do not rewrite the creative and do not reconnect. Tell me the exact error body including error_subcode. Then I will walk you through flipping the Meta app that issued this token from Development to Live.Meta returns error code 100 with "Unsupported get request" or "Object with ID does not exist"
Error 100 is Meta's catch-all for an id the token cannot resolve, and it has two very different causes that look identical in chat. The first is a placeholder: an agent that has not listed anything yet will invent an id such as act_123456789 or YOUR_AD_ACCOUNT_ID, and because the shape is valid, the call reaches Meta and comes back as a missing object rather than a bad argument. List first, then act. metaads_get_ad_accounts returns the real act_-prefixed ids, metaads_list_ads and metaads_read_adsets go a level down. The second cause is asset access: the object exists, but the identity behind your token was never assigned to it, so from Meta's point of view it does not exist. That distinction is the whole game, and Meta's error text will not make it for you.
Ask the agent to diagnose it:
Run metaads_get_ad_accounts and list every account id and name you can see. Then run metaads_get_user and tell me which identity the token belongs to. Do not retry the failed call until both have returned.Meta returns 403, error code 200, or "(#200) Requires ads_management permission"
The token is valid and the identity is real; the permission set on the token is short. Read calls such as metaads_get_insights need ads_read, and anything that creates or edits needs ads_management. A token minted quickly from the Graph API Explorer often carries only the default permissions, which is why the same connection can list ad accounts and then fail to create a campaign. Regenerate the token with both permissions, reconnect from the dashboard, and retry. Note this is a different failure from asset access: with the wrong permissions you get a permissions error, and with the wrong asset assignment you get an empty result or an error 100.
Ask the agent to diagnose it:
Run metaads_get_ad_accounts to confirm the connection works for reads. Then tell me the exact error body from the failed write call, including the code and subcode fields.Meta Ads calls stop working after weeks with "Error validating access token" or "Session has expired"
Meta access tokens expire, and short-lived ones expire fast. A token from the Graph API Explorer typically lasts around an hour unless it is exchanged for a long-lived one, and even a long-lived user token has a finite life. That is the practical argument for a Business Manager system user: its tokens do not expire on the same schedule and are not tied to your personal login session. When you see this error, nothing is wrong with the integration; the credential aged out. Generate a fresh token and reconnect Meta Ads from the dashboard.
Ask the agent to diagnose it:
Run metaads_get_user and report the exact error body if it fails, including the code and error_subcode fields. Do not retry the other Meta Ads calls.API key setup works but results look incomplete
Double-check that the API key for Meta Ads has the right scopes or account access. A valid key can still be too limited for some reads or writes.
FAQ
Is there a Hermes Agent Meta Ads integration?
Yes. ClawLink is the fastest way to connect Hermes to Meta Ads: link your Meta Ads account once in the browser and Hermes Agent can call the Meta Ads API through 93 ready-made tools — no custom code or token handling.
How do I connect Meta Ads to Hermes with ClawLink?
Install the plugin with hermes plugins install ClawLink-HQ/hermes-plugin --enable, then pair once: run hermes clawlink begin, approve the link in your browser, and run hermes clawlink finish. Connect Meta Ads in the dashboard and Hermes can use it from the next message — no config files, and the Meta Ads key you paste is stored server-side instead of in your environment.
How long does it take to connect Meta Ads to Hermes Agent?
About two minutes. Sign in, click Connect next to Meta Ads in the dashboard, authenticate, and Hermes Agent can use it from the next chat message.
Why use ClawLink instead of wiring Meta Ads up myself?
The alternative to ClawLink is usually manual API key setup plus your own token handling, permission troubleshooting, and tool plumbing for Hermes Agent. That is fine if you want to build and maintain the integration yourself. Most teams just want Meta Ads working from chat.
What exactly do I paste, and where do I get it?
A Meta system user access token with ads_read, ads_management, and business_management, for an identity that has Manage ad accounts access on the ad account you want the agent to work on. Use the in-dashboard Meta Ads setup guide rather than Graph API Explorer: Explorer tokens expire in about an hour and die when you change your password. The identity matters more than the token string: a token whose system user was never assigned the ad account connects successfully and then returns an empty list from metaads_get_ad_accounts, which reads like a broken integration and is actually an asset-access gap.
Do I need to create a Meta developer app or a Business Manager system user?
Yes, both, until ClawLink's hosted Meta Ads OAuth clears App Review. Create a Marketing API app on developers.facebook.com, connect it to your business portfolio, switch it from Development to Live (add your company's privacy policy URL and a Category under App settings → Basic first — App Review is not required for your own ad accounts), create a system user, assign the ad account with Manage ad accounts and the app with Develop app, then generate a Never-expiring token. The ClawLink dashboard guide covers each screen. A Development-mode app can still connect and read ads, but creating creatives or ads fails with Meta error_subcode 1885183 until you flip it to Live.
Is it safe to let an AI agent manage my Meta ad account?
Decide it on mechanics rather than on vibes, and there are four that matter here. First, reach: the token you paste defines the ceiling, so a token scoped to one ad account cannot touch the others, and a read-only token cannot spend money no matter what the agent decides to do. Second, revocation: you invalidate the connection from Meta's side by removing the token or the system user's asset access, and from ClawLink's side by deleting the connection, and neither depends on the other. Third, enumerability: the agent's ability is the tool list on this page, not an open API session; the write tools are named individually, including metaads_create_campaign, metaads_create_ad_set, metaads_create_ad, and metaads_update_campaign. Fourth, sequencing: campaign creation in this toolset takes several deliberate calls rather than one, so there is no single prompt that quietly launches spend. The conservative setup is a token that can read insights but not manage, until you have watched what the agent proposes.
Why does metaads_get_ad_accounts come back empty?
Because the identity behind the token has no ad accounts assigned to it. This is the most common first-run failure and it is not a ClawLink error. In Business Manager, assets are assigned to people and system users explicitly, and a brand-new system user starts with nothing. Assign it to the ad account, give it the right role, then retry. If the same token returns accounts in Meta's Graph API Explorer but not here, check that you copied the whole string.
Hermes paired but still can't use Meta Ads
Pairing is a two-step handshake: run hermes clawlink begin, approve the link in your browser, then run hermes clawlink finish. If you ran finish before approving, or the approval link expired, run hermes clawlink begin again to get a fresh link. Confirm the plugin was installed with --enable, then verify with hermes clawlink test.
Related
Connect SendPulse
SendPulse is a multichannel marketing platform for email, SMS, chatbots, CRM, automation, web push, and transactional messaging.
Connect HighLevel Location
HighLevel provides Location-scoped CRM, marketing, conversations, calendars, payments, and business automation APIs.
ActiveCampaign
Marketing automation, CRM, and email marketing