# How to connect Meta Ads to Hermes Agent (paste one token, 50 ad tools)

> Connect Meta Ads to Hermes Agent with ClawLink: paste a Meta access token once and 50 ad tools work from chat. No Business Manager system user to configure, nothing running on your machine.

Web version: https://claw-link.dev/hermes/meta-ads

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.

**Start here — paste this into Hermes to set up ClawLink:**

> Set up ClawLink for Hermes and tell me when it's ready.
> 1. Install the plugin: `hermes plugins install ClawLink-HQ/hermes-plugin --enable`
> 2. Start pairing with `hermes clawlink begin`. It prints an approval link, so show me the link and stop, don't wait.
> 3. I'll approve it in my browser, then reply "approved".
> 4. When I say approved, finish setup: `hermes clawlink finish`
> 5. Then run `hermes clawlink test` and tell me whether ClawLink is ready.

## Setup

It takes three steps to connect Hermes to Meta Ads.

1. **Install ClawLink** — add the plugin to Hermes Agent once.
2. **Connect Meta Ads** — one-click OAuth in the ClawLink dashboard.
3. **Use it from chat** — ask Hermes Agent in plain English.

**Alternative for any agent (no plugin needed):** if the Hermes Agent plugin route isn't available or doesn't work, any AI agent with shell access can use the ClawLink CLI instead:

```bash
npx -y @useclawlink/cli login          # sign in via browser — no API key to paste
npx -y @useclawlink/cli connect meta-ads  # connect Meta Ads (browser OAuth)
npx -y @useclawlink/cli actions meta-ads  # list available actions
npx -y @useclawlink/cli run meta-ads <action> --input '<json>'  # execute (add --confirm for writes)
```

### Install by command

The prompt above walks Hermes through this. By hand, it is four commands and a browser approval:

```bash
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 test
```

Then connect Meta Ads in the [ClawLink dashboard](https://claw-link.dev/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:

```bash
npx -y @useclawlink/cli login
```

`login` opens the same browser approval and stores a credential locally. Once Meta Ads is connected in the dashboard, that agent calls the same 50 Meta Ads tools over MCP. Full setup for MCP clients and shell agents: [connect apps to any AI agent](https://claw-link.dev/learn/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 50 Meta Ads tools your agent can call over [MCP](https://claw-link.dev/learn/what-is-an-mcp-server), with [hosted auth](https://claw-link.dev/learn/oauth-for-ai-agents) and nothing to run or maintain yourself. Using OpenClaw instead? The [OpenClaw Meta Ads integration](https://claw-link.dev/openclaw/meta-ads) works the same way.

Meta Ads is the one integration on ClawLink where you still bring a credential. Meta requires an approved app for third-party ad management, and ours is in review, so today you paste an access token into the connect screen once and ClawLink stores it server-side. What that replaces is the part people actually lose a day to: creating a Business Manager system user, assigning it to the right ad account, generating a token with ads_read and ads_management, and then rebuilding the whole chain when it expires. 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](https://claw-link.dev/hermes/facebook).** 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](https://claw-link.dev/hermes/instagram).

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

50 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 50.

### 30 of 50 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 |
| **List ad network analytics results** `metaads_list_ad_network_analytics_results` | Retrieve ad network analytics results for Facebook Audience Network |
| **List ads** `metaads_list_ads` | List all ads under an ad account using the Meta Marketing API |
| **List agencies** `metaads_list_agencies` | Retrieve agencies associated with a Meta Business or Ad Account |
| **List assigned pages** `metaads_list_assigned_pages` | Retrieve Facebook Pages assigned to a business user via Meta Marketing API |
| **List assigned users** `metaads_list_assigned_users` | List users assigned to a Facebook Page or Ad Account within a specific business context |
| **List business ad accounts** `metaads_list_business_ad_accounts` | Retrieve all ad accounts owned by a specific Business Manager |
| **List business invoices** `metaads_list_business_invoices` | Retrieve business invoices from Meta Marketing API |
| **List client ad accounts** `metaads_list_client_ad_accounts` | List all client ad accounts accessible to a business from Meta Ads |
| **List client apps** `metaads_list_client_apps` | Retrieve client apps associated with a Meta Business using the Marketing API |
| **List client instagram assets** `metaads_list_client_instagram_assets` | Retrieve Instagram assets that are shared with a business as a client using the Meta Marketing |
| **List client offsite signal containers** `metaads_list_client_offsite_signal_containers` | Retrieve client offsite signal container business objects for a business from Meta Marketing API |
| **List client pages** `metaads_list_client_pages` | Retrieve client pages associated with a Meta business |
| **List clients** `metaads_list_clients` | Retrieve client businesses associated with a Meta Business Manager |
| **List collaborative ads collaboration requests** `metaads_list_collaborative_ads_collaboration_requests` | Retrieve collaborative ads collaboration requests for a Meta Business using the Marketing API |
| **List collaborative ads suggested partners** `metaads_list_collaborative_ads_suggested_partners` | Retrieve collaborative ads suggested partners for a business from Meta Marketing API |
| **List initiated audience sharing requests** `metaads_list_initiated_audience_sharing_requests` | Retrieve initiated audience sharing requests for a business using the Meta Marketing API |
| **List managed partner ads funding source details** `metaads_list_managed_partner_ads_funding_source_details` | Retrieve managed partner ads funding source details for a Meta Business |
| **List owned apps** `metaads_list_owned_apps` | Retrieve apps owned by a business from Meta Marketing API |

## Example prompts

**Yesterday's spend by campaign**

> 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.

**Find the ads that stopped working**

> For my main ad account, use metaads_list_ads to pull the active ads, then metaads_get_insights on the last 14 days per ad. Flag anything whose CTR fell by more than a third versus the previous 14 days, and show the creative names with metaads_list_ad_creatives.

**Draft a campaign without launching it**

> Create a paused campaign with metaads_create_campaign in the account I name: objective OUTCOME_TRAFFIC, name "Q3 blog promo", status PAUSED. Then build one ad set with metaads_create_ad_set targeting the audience I describe next, also paused. Do not create ads or unpause anything, and show me what you made.

**Check what the token can actually reach**

> Run metaads_get_user, then metaads_get_ad_accounts, then metaads_list_owned_pages. Tell me which identity the connection uses, which ad accounts it can see, and which pages it manages, so I know the blast radius before we go further.

## 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_accounts` is the entry point, and everything else takes ids that come from a previous call. Ad account ids carry an `act_` 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 setting `status` to `PAUSED` at each step is the safe way to draft.
- **`metaads_get_object` is 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_insights` works 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`, and `metaads_list_clients` read 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_image` comes 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. | 50 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 50 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](https://claw-link.dev/hub/composio-alternatives) comparison.

### 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 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:

```text
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:

```text
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:

```text
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.

### 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 50 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 access token with ads_read and ads_management permissions, for an identity that has access to the ad account you want the agent to work on. Most people generate one from Meta's Graph API Explorer for a first test, then move to a longer-lived token or a Business Manager system user token for anything ongoing. The identity matters more than the token type: a token belonging to a user or system user with no access to the ad account will connect successfully and then return an empty list from metaads_get_ad_accounts, which reads like a broken integration and is actually a permissions gap.

### Do I need to create a Meta developer app or a Business Manager system user?
You do not need to create an app. You may still want a system user, and the distinction is worth understanding. A personal user token is tied to you and to your session, so it expires and takes the agent's access with it. A Business Manager system user is a non-human identity that belongs to the business, is assigned to specific ad accounts, and issues tokens that do not die when you change your password. For an agent that runs unattended, that is the more stable choice. Either way you are pasting one string into the connect screen rather than wiring an app.

### 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

- [Hermes ActiveCampaign integration](https://claw-link.dev/hermes/activecampaign) — Marketing automation, CRM, and email marketing
- [Benchmark Email tools](https://claw-link.dev/hermes/benchmark-email) — Benchmark Email is a comprehensive email marketing platform offering tools for creating, sending, and analyzing email campaigns.
- [Hermes Mailchimp integration](https://claw-link.dev/hermes/mailchimp) — Create email campaigns and manage audiences