By Ira Bodnar, Ryze AI · Updated · Connector tested November 14, 2026
Quick answer
The main way to connect Hermes Agent to Meta Ads is the Ryze AI connector. Link Meta Ads once in a Ryze AI workspace with your Meta login, add a ryze entry with the URL https://connector.get-ryze.ai/mcp and auth: oauth under mcp_servers in ~/.hermes/config.yaml, then run hermes mcp login ryze and click Allow connection. Start a new session and ask for a Meta Ads report.
- In Ryze AI open Integrations, find Meta Ads under Advertising and click Connect with your Meta login
- Add the ryze entry to the mcp_servers block of ~/.hermes/config.yaml
- Run hermes mcp login ryze and click Allow connection on the Ryze AI page
- Start a new session or run /reload-mcp, then ask your first Meta Ads question
Hermes Agent to Meta Ads at a glance
| Fact | Detail |
|---|---|
| Main way to connect | The Ryze AI connector, a remote HTTP MCP server that Hermes Agent reads from one ryze entry under mcp_servers in ~/.hermes/config.yaml |
| Connector address | https://connector.get-ryze.ai/mcp, identical for every user |
| How Hermes Agent signs in | OAuth with auth: oauth, completed once with hermes mcp login ryze. A Ryze AI API key sent as a bearer header from ~/.hermes/.env is the alternative |
| Meta Ads tools | 10 in total: 7 that read, 2 that write and 1 that deletes |
| Changes to the account | Possible when the connected Meta login has a role that may edit ads. Setting trust: untrusted on the ryze entry makes Hermes Agent ask before write-capable calls |
| Other data in the same chat | Any other Ryze AI platform connected in the workspace is available at the same address. This guide covers Meta Ads |
| Hermes Agent plan | None. Hermes Agent is open source under the MIT license per its GitHub repository and runs on your own machine or server |
| Ryze AI price | Paid Ads costs $89 per month after a 7-day free trial. Adding the connector costs nothing |
| Meta's own option | The Meta ads MCP server at https://mcp.facebook.com/ads, in open beta since April 29, 2026. Meta's pages do not name Hermes Agent and say it works with any MCP-compatible AI agent |
| Meta sign-in | OAuth with Meta, with 11 permissions requested. No key or token to copy |
| Last tested | Connector calls on November 14, 2026. The steps inside Hermes Agent were not run |
Before you start
- Hermes Agent installed. It is open source from Nous Research, licensed MIT per its GitHub repository, and self-hosted, so there is no plan tier to buy. MCP support is configured in ~/.hermes/config.yaml.
- A Meta login with access to your ad accounts. The Ryze AI help center asks for at least Advertiser access on the ad account, and Admin to allow changes, ideally granted through Meta Business Manager. A login with view-only access can run reports but cannot change anything.
- A Ryze AI workspace on a plan or free trial. Paid Ads is $89 per month with a 7-day free trial; Agency is $279 per month. Connecting the connector is free, but the Meta Ads tools need an active plan or trial.
How to connect Hermes Agent to Meta Ads with OAuth
Two steps happen in Ryze AI and Meta, the rest in Hermes Agent. The connector URL is the same for every user.
Connect Meta Ads in Ryze AI
Create a Ryze AI account or sign in, open Integrations in the left sidebar and find Meta Ads under Advertising. Click Connect, sign in to Meta and approve access with every requested permission checked.
Check the connection
Back in Ryze AI the Meta Ads card shows Connected. There is no ad account to pick: Ryze AI sees every ad account that login can reach. To choose the accounts the agent works with first, click View on the card and use Agent default accounts.
Add the ryze entry to config.yaml
Open ~/.hermes/config.yaml and add a ryze server under mcp_servers. Add the entry and then run the login in the next step, because editing config.yaml in a running session reloads MCP with a 30-second timeout, which is too short for a browser sign-in.
mcp_servers: ryze: url: "https://connector.get-ryze.ai/mcp" auth: oauthSign in to the connector
Run hermes mcp login ryze. Hermes Agent prints an authorize URL and opens your browser when it can. Sign in on the Ryze AI page and click Allow connection. Hermes Agent caches the tokens at ~/.hermes/mcp-tokens/ryze.json and reuses them until a refresh fails.
Load the tools
Start a new session, or run /reload-mcp inside a running one. Hermes Agent registers each tool as mcp_<server>_<tool>, so the Meta Ads tools start with mcp_ryze_meta_ads. To see what the server answers, run hermes mcp test ryze.
Ask your first question
Ask: List every Meta ad account my login can reach, with id, name and currency.
The Ryze AI help article for Meta Ads covers the Meta side of the connection, and the Ryze AI help article on API keys and the MCP endpoint covers the connector URL.
Source for the Hermes Agent steps: Hermes Agent MCP documentation, opened November 18, 2026.
API key, tool filters and headless hosts
Hermes Agent keeps every MCP server in one file, ~/.hermes/config.yaml. These are the variations that matter for this connector.
A Ryze AI API key instead of OAuth
Create a key in Ryze AI under Workspace Settings > Profile > API keys > Create key and copy it, because it is shown once. Put RYZE_API_KEY with the rk_live_ key in ~/.hermes/.env and reference it in the header, since Hermes Agent substitutes ${VAR} placeholders in headers from the environment. Run /reload-mcp afterwards. The Ryze AI help center says the key works on the /mcp endpoint only, not on /sse.
mcp_servers:
ryze:
url: "https://connector.get-ryze.ai/mcp"
headers:
Authorization: "Bearer ${RYZE_API_KEY}"Show Hermes Agent only the read tools
Each server entry accepts tools.include and tools.exclude, and both take exact tool names or glob patterns. This entry registers the 7 Meta Ads read tools and nothing else from the connector, which also hides the tools of every other platform in the workspace. It hides tools from Hermes Agent only. For a hard read-only guarantee, connect a Meta login that only has read access.
mcp_servers:
ryze:
url: "https://connector.get-ryze.ai/mcp"
auth: oauth
tools:
include:
- meta_ads__listAdAccounts
- meta_ads__getAccountSummary
- meta_ads__runRawInsights
- meta_ads__listCreatives
- meta_ads__getCreative
- meta_ads__listLeadForms
- meta_ads__runGraphReadA remote or headless host
When Hermes Agent runs on a server and your browser is on another machine, the local callback cannot reach the browser. The client notes for this guide list one fix: paste the redirect URL back at the prompt that hermes mcp login prints instead of using a local browser. The API key route above avoids the browser entirely.
hermes mcp login ryzeReconnecting Meta later
Meta access expires more often than Google access: the Ryze AI help center shows Reconnect needed after two-factor or Business Manager role changes. Reconnect on the Meta Ads card in Ryze AI. The Hermes Agent entry does not change, because the Meta login lives in Ryze AI.
Reloading and timeouts
The Hermes Agent page read for this guide names connect_timeout for the first connection and oauth.timeout for the browser approval window, and it gives no default for the tool-call timeout. If long Insights reports are cut short on the Hermes Agent side, check the timeout setting on the ryze entry. Reports that ask Meta for a lot of data can also fail on Meta's side with error 100, subcode 1487534.
mcp_servers:
ryze:
url: "https://connector.get-ryze.ai/mcp"
auth: oauth
connect_timeout: 60
oauth:
timeout: 300Hermes Agent and MCP: the facts in one table
| Topic | What the Hermes Agent documentation says |
|---|---|
| Where servers are added | ~/.hermes/config.yaml under mcp_servers |
| Transports | Local stdio servers (command and args) and remote HTTP servers (url) |
| Sign-in | auth: oauth does discovery, PKCE and token refresh. Hermes Agent tries a Client ID Metadata Document first and falls back to dynamic client registration. Static bearer headers also work |
| Token storage | ~/.hermes/mcp-tokens/<server>.json, reused until refresh fails |
| Tool names | mcp_<server_name>_<tool_name>, so a server named ryze registers its tools under names that start with mcp_ryze_ |
| Approval | trust: untrusted on a server entry triggers approval prompts for write operations |
| Filtering | tools.include and tools.exclude per server, with glob support. enabled: false skips the server |
| Reload | /reload-mcp, or a new session. Editing config.yaml in a running session reloads MCP with a 30-second timeout |
| Diagnosis | hermes mcp test <name> checks a server, and the startup log agent.log names every server that failed and why |
| Proxies | HTTP servers honor HTTPS_PROXY, HTTP_PROXY and NO_PROXY |
| Plan | None. Open source, self-hosted |
Sources: Hermes Agent MCP documentation, NousResearch/hermes-agent on GitHub. Opened November 18, 2026.
Other clients
The same URL works in other MCP clients. Meta Ads is connected once in Ryze AI, so nothing changes on the Meta side.
Claude Code
Run claude mcp add --transport http ryze https://connector.get-ryze.ai/mcp, then claude mcp login ryze. Meta Ads is linked once in Ryze AI, so the Meta side does not change from client to client. The connector calls behind this guide were run from Claude Code.
Claude and ChatGPT
In Claude open Customize > Connectors, choose Add custom connector and enter https://connector.get-ryze.ai/mcp. In ChatGPT the full custom MCP flow is for Business and Enterprise/Edu plans, and Pro users get read and fetch permissions only. The Ryze AI help center has the exact screens for both. See the Claude guide and the ChatGPT guide.
Codex
Codex takes codex mcp add ryze --url https://connector.get-ryze.ai/mcp followed by codex mcp login ryze. The Codex guide has the Meta Ads prompts.
Meta Ads permissions and Hermes settings
Two sides decide what Hermes Agent can reach in Meta Ads: the Meta login you connect in Ryze AI, and the settings on the ryze entry in Hermes Agent. The Ryze AI connection uses no Meta developer app, system user token or API key of your own.
- The Meta login
- Signs in with OAuth. It needs access to at least one ad account, and the Ryze AI help center asks for Advertiser access at minimum and Admin to allow changes. Every request runs with that login's rights.
- Which accounts
- Every ad account the login can reach. Agent default accounts picks the ones the agent works with first, and the rest stay reachable by naming them. Over MCP every meta_ads tool takes an optional connection_id.
- The Ryze AI sign-in from Hermes Agent
- hermes mcp login ryze, or an API key in a bearer header. Both reach the same workspace tools. The OAuth screen lets you choose which workspaces the client can use.
- The Hermes Agent settings
- trust, tools.include and tools.exclude on the ryze entry decide which tools Hermes Agent sees and when it asks first. They are client-side settings and do not change what the Meta login may do.
The 11 Meta permissions of the connection
When you link Meta Ads in Ryze AI, the Meta sign-in asks for 11 permissions. The names come from the Ryze AI Meta Ads facts. The descriptions are Meta's wording on its permissions reference, opened November 14, 2026.
| Scope | Meta's description |
|---|---|
| ads_management | Allows your app to both read and manage the Ads account it owns, or has been granted access to, by the Ad account owner. |
| ads_read | Allows your app to access the Ads Insights API to pull Ads report information for Ad accounts you own or have been granted access to. |
| business_management | Allows your app to read and write with the Business Manager API. |
| pages_show_list | Allows your app to access the list of Pages a person manages. |
| pages_read_engagement | Allows your app to read content posted by the Page, read followers data and read metadata and other insights about the Page. |
| pages_manage_ads | Allows your app to manage ads associated with the Page. |
| leads_retrieval | Allows your app to retrieve and read all information captured by a lead ads form. The connector has no tool that exports leads; meta_ads__listLeadForms lists the forms on a Page. |
| catalog_management | Allows your app to create, read, update and delete business-owned product catalogs that the user is an admin of. |
| instagram_basic | Allows your app to read an Instagram account profile's info and media. |
| instagram_manage_comments | Allows your app to create, delete and hide comments on behalf of the Instagram account linked to a Page. |
| public_profile | Allows an app to read the Default Public Profile Fields on the User node. Granted automatically to all apps. |
Ad account roles
Meta's help page says ad accounts have 3 permission roles. Meta's table says the Advertiser role can create and edit ads, while the Ryze AI help center asks for Admin to allow changes. When you want a login that cannot change anything, the Analyst role is the view-only one.
| Ad account role | What Meta says it can do |
|---|---|
| Admin | View ads, access reports, create and edit ads, edit payment method, manage admin permissions. |
| Advertiser | View ads, access reports, create and edit ads. Cannot change the payment method or add or remove other people's access. |
| Analyst | View ads and access reports only. |
To advertise for a Facebook Page you need full control or partial access (Ads) to the Page, and an Instagram ad needs a professional Instagram account connected to that Page, according to Meta's help page. One Meta login reaches every ad account it can access. Several Meta logins can be connected to one workspace, and a star marks the primary one that the agent uses when no account is named.
What the default connection leaves out: organic Facebook Page and Instagram posts (the Ryze AI Meta app does not hold pages_manage_posts or instagram_content_publish), comments on a Facebook Page (no pages_read_user_content), lead exports, restoring archived or deleted objects, changing the attribution window in meta_ads__getAccountSummary (meta_ads__runRawInsights can request other windows) and any ad account the connected login cannot open. Meta's own server asks for ads_mcp_management, which is not in the Ryze AI list, because Ryze AI calls the Marketing API directly. The Marketing API access tier of the Ryze AI Meta app was not visible in any response and was not checked.
Sources: Meta permissions reference, Meta ad account roles, Marketing API authorization. Checked November 14, 2026.
Removing access
To remove access, click View on the Meta Ads card in Ryze AI and disconnect the login. In Hermes Agent, set enabled: false on the ryze entry or delete it from config.yaml, and delete ~/.hermes/mcp-tokens/ryze.json to drop the cached tokens.
What Hermes Agent can do in Meta Ads
The Ryze AI connector exposes 10 Meta Ads tools: 7 read, 2 write and 1 delete. Calls go through Meta's official API, and each one runs with the permissions of the Meta login you connected. In Hermes Agent the names appear with the mcp_ryze_ prefix.
| Tool | Type | What it does |
|---|---|---|
| meta_ads__listAdAccounts | Read | Lists every Meta ad account the connected user can access, with id, name and currency. |
| meta_ads__getAccountSummary | Read | Returns aggregate metrics for a Meta ad account on Meta's default attribution window. |
| meta_ads__runRawInsights | Read | Runs a raw Insights query at account, campaign, ad set or ad level with breakdowns, filters and custom attribution windows. |
| meta_ads__listCreatives | Read | Lists the ad creatives in a Meta ad account. |
| meta_ads__getCreative | Read | Gets one Meta ad creative by id. |
| meta_ads__listLeadForms | Read | Lists the lead generation forms on a Facebook Page. |
| meta_ads__runGraphRead | Read | Reads any Meta Graph API object or edge, such as paused campaigns, targeting specs or the ad account activity log. |
| meta_ads__runGraphWrite | Write | Creates or updates campaigns, ad sets, ads, creatives and other objects through the Meta Graph API. |
| meta_ads__uploadImageFromUrl | Write | Uploads an image from a URL to a Meta ad account and returns an image hash for a creative. |
| meta_ads__runGraphDelete | Delete | Deletes or archives Meta objects. Its description says it is meant for an explicit item-by-item approved list. |
Approvals in Hermes Agent
In Hermes Agent, approval for MCP tools is set per server. Adding trust: untrusted to the ryze entry triggers approval prompts for write operations on that server. /yolo, --yolo and approvals.mode: off skip the prompt, and scheduled tasks on the Ryze AI side run without an approval step. Budget cuts and pauses that the Ryze AI agent finds on its own go to the Ryze AI Inbox and change nothing until you approve. Whether the Ryze AI tools carry the readOnlyHint annotation was not checked, so expect prompts on some reads as well.
mcp_servers:
ryze:
url: "https://connector.get-ryze.ai/mcp"
auth: oauth
trust: untrustedMeta Ads limits in numbers
Meta meters the Marketing API per ad account over one hour, and every Meta figure below comes from a Meta page named in the sources line. The last row is an input limit from the connector's tool definitions as listed on November 14, 2026.
| Limit | Number |
|---|---|
| Call score per ad account | A read scores 1 point and a write 3. Development tier: maximum score 60, blocked 300 seconds at the maximum. Full access: maximum 9,000, blocked 60 seconds. Error 17 (subcode 2446079) or 613 (subcode 1487742) |
| Ads management quota | Per ad account in one hour: 100,000 on Full access or 300 on the development tier, plus 40 times the number of active ads. Error 80004 |
| Ads Insights quota | Per ad account in one hour: 190,000 on Full access or 600 on the development tier, plus 400 times the number of active ads, minus 0.001 times user errors. Error 80000 |
| Edits to one object | One edit per object every 30 seconds, per app. Meta's page states this per object, not per ad account. Error 613, subcode 4841018 |
| Ad set budget changes | An ad set's daily or lifetime budget can change 4 times per hour, then the change is blocked for an hour. Error 613, subcode 1487632 |
| Create and edit bursts | 100 requests per second per app and ad account on create and edit operations for campaigns, ad sets and ads. Error 613, subcode 5044001 |
| Insights history | 37 months. A time range that starts earlier fails with error 3018 (refused on November 14, 2026 in the connector test) |
| Time slices | time_increment as a number is 1 to 90 days, or monthly, or all_days. A value of 91 was refused on November 14, 2026 |
| Data freshness | Insights refresh every 15 minutes and do not change after 28 days of being reported |
| Report size | No fixed row limit is published. Too much data in one call returns error 100 with subcode 1487534 |
| Reach with breakdowns | Since June 10, 2025 reach, frequency and cpp are not returned for standard queries that use breakdowns and start dates more than 13 months old |
| Graph read through Ryze AI | The fields list of meta_ads__runGraphRead is at most 2,048 characters and the path at most 4,096. A longer fields list is refused by the connector before it reaches Meta |
Sources: Marketing API rate limiting, Insights API best practices, Insights reference. Checked November 14, 2026. The Ryze AI row comes from the connector's tool definitions as listed on November 14, 2026.
Meta Ads calls in the test
On November 14, 2026 eleven Meta Ads calls went through the Ryze AI connector from Claude Code, on the default connection to a real workspace. One was meant to return data and ten were built to fail. Ad account IDs and every number from the account are left off this page. These calls did not come from Hermes Agent.
| Tool | What the call asked for | Result |
|---|---|---|
| meta_ads__listAdAccounts | The ad accounts the connected login reaches | Worked. A list with id, account_id, name and currency for each account |
| meta_ads__runGraphRead | The campaigns edge of an ad account with a made-up field name | Did not fail. Rows with only an id and paging cursors came back, and the unknown field was ignored |
| meta_ads__runGraphRead | An ad account node with a made-up field name | Did not fail. Only the id of the node came back |
| meta_ads__runGraphRead | An object ID that does not exist | Refused by Meta, code 100, subcode 33 |
| meta_ads__runGraphRead | An edge that does not exist | Refused by Meta, code 2500 |
| meta_ads__runGraphRead | A fields value of 2,100 characters | Refused by the Ryze AI connector, invalid_arguments, maximum 2048 |
| meta_ads__runRawInsights | A field that does not exist | Refused by Meta, code 100 |
| meta_ads__runRawInsights | An ad account ID the login cannot reach | Refused, status not_allowed with Meta error 200 |
| meta_ads__runRawInsights | An attribution window that does not exist, 99d_click | Refused by Meta, code 100, with the list of 26 accepted values |
| meta_ads__runRawInsights | A time range starting in January 2020 | Refused by Meta, code 3018 |
| meta_ads__runRawInsights | timeIncrement 91 | Refused by Meta, code 100, maximum 90 |
None of the responses carried a rate-limit header or a usage percentage. No successful Insights read was run, because it would return metric values. The tool description says one unknown Graph field fails the whole read, yet two calls with a made-up field returned ids, so do not expect an error for an unknown Graph field. The error for an unknown Insights field is confirmed.
First 3 prompts to run
Each answer comes from your own account, so this page describes what comes back instead of showing a result. Hermes Agent picks the tool itself; the names are listed so you can check which one ran.
1. List the ad accounts the login can reach
List every Meta ad account my connected login can open, with id, name and currency.
Tools used: meta_ads__listAdAccounts
What comes back: The ad accounts under the connected login. Use an id from this list in later questions, because a wrong id fails with the same message as a missing permission.
2. Results by placement
For the last 30 days, break spend, impressions and clicks down by placement at campaign level for ad account <id>.
Tools used: meta_ads__runRawInsights
What comes back: Rows per campaign and placement with the fields you asked for. runRawInsights offers 4 levels (account, campaign, adset, ad) and 8 breakdowns, among them age, gender, country, device_platform and platform_position.
3. Who changed what
Read the activity log of ad account <id> and show who changed budgets or status recently.
Tools used: meta_ads__runGraphRead (the activities edge)
What comes back: Entries from the ad account activity log that show who changed what. A first page is not the whole account, so ask Hermes Agent to follow paging.next until it is absent.
When you want a change, describe it in plain words, such as pausing a campaign or lowering an ad set budget. With trust: untrusted on the ryze entry, Hermes Agent asks before it runs a write-capable call. Budgets pass through in minor units, so 5000 means 50.00 in the account currency.
10 jobs to hand to Hermes Agent
Ten jobs you can give Hermes Agent, each with the tool that does the work. In the connector test only the account list call returned data, and no job below was run from Hermes Agent.
| Job | Ask Hermes Agent | Tool | Works on the default connection |
|---|---|---|---|
| List ad accounts | List every Meta ad account this login can reach. | meta_ads__listAdAccounts | Works. Tested on November 14, 2026 |
| Spend, ROAS and CTR | Give spend, ROAS and CTR for this ad account over this date range. | meta_ads__getAccountSummary | Works on Meta's default attribution window, which this tool cannot change |
| Breakdowns and attribution windows | Break results down by age, gender, country, device or placement, or reproduce a client's attribution window. | meta_ads__runRawInsights | Works. Reports start at most 37 months back. Only refusals were run |
| Creative list | List the ad creatives in this ad account. | meta_ads__listCreatives | Works. 100 creatives per call by default, 1,000 at most |
| One creative | Open this creative id and show its copy, image and call to action. | meta_ads__getCreative | Works. Needs the creative id |
| Lead forms | List the lead generation forms on this Facebook Page. | meta_ads__listLeadForms | Works with a role on the Page. It lists forms and does not export leads |
| Activity log and paused campaigns | Show who changed budgets or status, or list paused campaigns and their targeting specs. | meta_ads__runGraphRead | Works. Follow paging.next until it is absent |
| Campaign edits | Create this campaign, adjust this budget, pause or resume this ad set, or swap this creative. | meta_ads__runGraphWrite | Works when the login's role may edit ads. Meta allows 4 budget changes per ad set per hour |
| Image upload | Upload this image from a URL and give me the image hash for a new creative. | meta_ads__uploadImageFromUrl, meta_ads__runGraphWrite | Works with the same role. Video goes through runGraphWrite with a video URL |
| Archive or delete | Archive these named campaigns, ad sets or ads. | meta_ads__runGraphDelete | Works. Archived and deleted objects cannot be restored, so give an item-by-item list |
5 ways to connect Hermes Agent to Meta Ads
Five routes give Hermes Agent access to Meta Ads. This guide treats the Ryze AI connector as the main way: Hermes Agent adds one hosted address, the Meta sign-in happens once in Ryze AI, and no Meta developer app or system user token is needed. Each setup cell says how the route would work in Hermes Agent; none of them was run there.
| Way | Runs where | Setup in Hermes Agent | What it can do in Meta Ads | Price |
|---|---|---|---|---|
| Ryze AI connector (the main way) | Hosted by Ryze AI, one address for every user | A ryze entry with url and auth: oauth, then hermes mcp login ryze. Or a bearer header with a Ryze AI API key read from ~/.hermes/.env | 10 tools: ad account list, account summary, raw Insights with breakdowns and attribution windows, creatives, lead form list, any Graph read, plus Graph write, image upload and one delete tool | Paid Ads is $89 per month with a 7-day free trial; Agency is $279 per month |
| Meta ads MCP server, from Meta | Hosted by Meta at https://mcp.facebook.com/ads | A url entry with auth: oauth could point at it. Meta's pages do not name Hermes Agent, and its tokens can also be sent as a bearer header. Meta's OAuth metadata lists a registration endpoint and PKCE, and none of this was run in Hermes Agent | Reporting, ad creation and management, catalogs, datasets, Business Help Center search, A/B tests and lift studies, and the activity log. Meta's category pages list 88 distinct tools as counted on November 14, 2026. New campaigns are created paused | Meta says there is no additional cost from Meta to connect. Open beta since April 29, 2026, and not all ad accounts have access yet |
| Ads CLI (package meta-ads), from Meta | On your computer, macOS or Linux | Install it, then let an agent that can run shell commands call it. Meta's pages name no assistant, and whether Hermes Agent should run it was not checked here. It signs in with a system user access token | Campaigns, ad sets, ads, creatives, insights, catalogs, datasets, ad accounts and Pages. Resources are created paused by default | No price on Meta's pages. Version 1.3.1 was the newest on PyPI on November 14, 2026 |
| Composio | Hosted | Composio lists Hermes on its Meta Ads toolkit page. Ryze AI's older guide to Hermes Agent uses a config.yaml entry for https://connect.composio.dev/mcp with a Composio API key header. Meta connections go through your own OAuth app, which you register with Meta | 99 tools listed, read and write, among them Create Campaign, Create Ad Set and Delete Campaign | Composio's pricing page: the free plan stops at 10,000 app tool calls a month, and Standard is $18 per seat per month |
| Pipeboard Meta Ads MCP | Hosted at https://meta-ads.mcp.pipeboard.co/, or self-hosted with your own Meta app | Create a Pipeboard account, connect Facebook Ads and add the remote URL. Its README names Claude, ChatGPT, Perplexity and Cursor, not Hermes Agent | 42 tools in the README's family table and 28 in its numbered list. Writes ask for confirmation and new campaigns start paused, per the README | Free: 30 weekly AI tool executions and 2 ad account slots. Pro is $29.90 per month |
Ryze AI's older post, How to connect Google and Meta Ads with Hermes Agent, sets up Composio. It is a different route from this guide and both can stay in config.yaml under different server names. With the Ryze AI connector your Meta Ads data passes through Ryze AI. With Meta's own server it goes from Meta to your agent, which Meta describes as authorized through the AI agent.
Options that do not fit Hermes Agent
- Meta AI business assistant. Meta's own assistant inside Ads Manager. It is not a route for an outside assistant, and Meta positions it next to the connectors.
- Zapier MCP. Zapier has no Meta Ads or Facebook Ads MCP page (both addresses returned 404 on November 14, 2026). Its Facebook Lead Ads, Custom Audiences and Conversions pages list no action that reads campaign results or edits a campaign.
- Windsor.ai. A hosted data connector with 20 write actions for Meta Ads. Its page names Claude, ChatGPT, Copilot, Gemini Enterprise and Perplexity, not Hermes Agent.
- Coupler.io. Read-only for the AI tool, working from data synced on a schedule. It cannot create or change campaigns.
Which one to pick
Ryze AI is the best way to connect Hermes Agent to Meta Ads for reports and campaign changes from one hosted address, with these caveats: you need a Ryze AI plan once the trial ends, your Meta Ads data passes through Ryze AI, the Hermes Agent steps in this guide come from its documentation rather than a test run, and organic posts, Page comments and lead exports stay out of reach. Try Meta's own ads MCP server instead if you want Meta alone in the path and your ad accounts have access to the open beta, and use Composio or Pipeboard when your team already pays for one of them.
Sources: Meta ads MCP server overview, Meta ads MCP server get started, Meta marketing page for the server, Meta Ads CLI overview, Composio Meta Ads toolkit, Composio pricing, Pipeboard Meta Ads MCP, Zapier MCP quickstart, Windsor.ai Facebook Ads MCP, Hermes Agent MCP documentation. Checked November 14, 2026.
Hermes Agent, Meta Ads and MCP: dates that matter
| Date | What happened |
|---|---|
| June 10, 2025 | Insights API change: reach with breakdowns is no longer returned for start dates more than 13 months old, and the API follows each ad set's attribution setting as Ads Manager does. |
| April 29, 2026 | Meta announced Meta ads AI connectors in open beta: the ads MCP server and the Ads CLI. |
| May 4, 2026 | Meta renamed Ads Management Standard Access to Marketing API Access Tier (Limited and Full access) and lowered the Full access threshold from 1,500 to 500 Marketing API calls in 15 days. |
| July 16, 2026 | Meta added support for connecting any AI application with your own developer app, and ads MCP server rules for people with full control of a business portfolio. |
| October 30, 2026 | meta-ads 1.3.1 was uploaded to PyPI, the newest release on November 14, 2026. |
| November 4, 2026 | Marketing API v27.0 became the current version. v25.0 is available until February 23, 2027. |
| November 14, 2026 | The Ryze AI connector loaded 10 meta_ads tools in the test for this guide. |
| November 18, 2026 | The Hermes Agent MCP documentation was read again for this guide. Run hermes mcp test ryze after you update Hermes Agent. |
Sources: Hermes Agent MCP documentation, Meta ads AI connectors announcement, Marketing API changelog, Marketing API versions, meta-ads on PyPI. Checked November 14, 2026.
How this guide was tested
The Ryze AI connector and the Meta pages behind this guide were checked on November 14, 2026, and the Hermes Agent documentation was read on November 18, 2026. Each row is something that was run or read, with what it returned.
| What was run | What came back |
|---|---|
| The tool list, loaded in Claude Code signed in to the connector | 10 Meta Ads tools under the names in the tools table: 7 read, 2 write, 1 delete. |
| One Meta Ads read that returns data | It worked: the list of reachable ad accounts. The values stay off this page. |
| Ten Meta Ads calls built to fail | Eight were refused with the messages shown under errors and fixes, and two came back with ids only. |
| Quota during the calls | No rate limit was reached, so no quota error message was collected. |
| Meta's own server, called without a sign-in | It returned HTTP 401 and named 10 scopes in its challenge. |
| The Hermes Agent MCP documentation, read on November 18, 2026 | It describes remote HTTP servers with auth: oauth, the token cache path, hermes mcp login, /reload-mcp, tool filters and the trust setting. That page is the source of every Hermes Agent step on this page. |
Not run for this guide: every step inside Hermes Agent. Hermes Agent was not installed, so hermes mcp login ryze and the config.yaml entries follow its documentation. On paper the sign-in fits: Hermes Agent falls back to dynamic client registration, which is the only registration method the Ryze AI connector supports. The Ryze AI help center has no page for Hermes Agent, and Ryze AI was not tested there. The write, upload and delete tools were not run, and neither were the account summary, creative and lead form tools. No call was made to Meta's own ads MCP server or the Ads CLI with a sign-in.
Hermes Agent and Meta Ads errors and fixes
Exact error messages from the test
These messages came back in the test on November 14, 2026. If Hermes Agent shows one of them, the cause is in the request or the Meta access, not in the connection to Ryze AI.
| Message | What it means | What to do |
|---|---|---|
| Unsupported get request. Object with ID '...' does not exist, cannot be loaded due to missing permissions, or does not support this operation. | Code 100, subcode 33. The ID is wrong, or the connected Meta login has no access to that object. Meta gives the same message for both. | Ask Hermes Agent to list ad accounts or campaigns first and use an ID from that list. If the object exists, check the login's access in Meta Business Manager. |
| (#100) not_a_field_xyz is not valid for fields param. | The Insights API does not know that field name. The tool description says roas is purchase_roas, and status, placement and creative are not Insights fields. | Ask again with a valid Insights field, or let the agent read object attributes with meta_ads__runGraphRead. |
| Meta Graph error (code 200): (#200) Ad account owner has NOT grant ads_management or ads_read permission | The connector returned status not_allowed. The connected Meta login has no access to that ad account, or the ID is wrong. | Use an ID from meta_ads__listAdAccounts, give the login access in Meta Business Manager, or connect another Meta login in Ryze AI. |
| (#100) action_attribution_windows[0] must be one of the following values: 1d_view, 7d_view, 28d_view, 1d_click, 7d_click, 28d_click, ... | The attribution window name is not one Meta accepts. The message lists 26 accepted values. | Ask for a window from the list. The tool description names 1d_click, 7d_click, 28d_click and 1d_view as the ones to use. |
| (#3018) The start date of the time range cannot be beyond 37 months from the current date. | Meta keeps 37 months of Insights data, and the earliest date in the message is 37 months before the day of the call. | Start the report inside the last 37 months. |
| (#100) Param name_placeholder must be a number less than or equal to 90 | A time slice in days can be 1 to 90. Meta prints name_placeholder where the parameter name time_increment should be. | Use a number from 1 to 90, or monthly, or all_days. |
| Unknown path components: /not_an_edge_xyz | Code 2500. The path names an edge that does not exist on that object. | Use a real edge such as campaigns, adsets, ads, adcreatives, customaudiences or activities. |
| Too big: expected string to have <=2048 characters | Status invalid_arguments from the Ryze AI connector. The call did not reach Meta. The fields list for one Graph read may be at most 2,048 characters. | Ask for fewer fields per call, or split the read. |
Other problems
- The tools do not show up in Hermes Agent
- Start a new session or run /reload-mcp. Then run hermes mcp test ryze, which reports what the server answered. Also check that no tools.include or tools.exclude filter hides them, that the entry is not set to enabled: false and that Meta Ads shows Connected in Ryze AI.
- The browser sign-in times out
- Editing config.yaml inside a running session triggers an automatic MCP reload with a 30-second timeout, too short for OAuth. Add the entry, then run hermes mcp login ryze. If you need longer to approve, set oauth.timeout on the entry.
- Hermes Agent cannot reach the callback on a server
- Use the paste-back prompt that hermes mcp login prints, or use a Ryze AI API key in a bearer header.
- A 401 or 403 from the connector
- Run hermes mcp login ryze again. With an API key, check that RYZE_API_KEY is set in ~/.hermes/.env and that the header reads Bearer followed by the rk_live_ key.
- Meta Ads shows Reconnect needed
- Meta access expires more often than Google access, for example after two-factor or Business Manager role changes. Reconnect on the Meta Ads card in Ryze AI.
- A write fails with a permission error
- The connected Meta login probably has an Analyst role or no role on that ad account. Roles are set in Meta Business Manager, not in Ryze AI or Hermes Agent. The Ryze AI help center asks for Admin to allow changes.
- Several creative changes in a row fail
- Meta's rate limit page allows one edit per object every 30 seconds per app (error 613, subcode 4841018), and 4 budget changes per ad set per hour. Wait, then ask again.
- Requests fail behind a proxy
- HTTP servers honor HTTPS_PROXY, HTTP_PROXY and NO_PROXY, so set them in the environment Hermes Agent starts from.
Terms on this page
- Hermes Agent
- An open source AI agent from Nous Research that you run on your own machine or server. Its MCP servers are listed in ~/.hermes/config.yaml under mcp_servers.
- MCP
- Model Context Protocol, an open standard that lets large language models interact with external data and applications. The Ryze AI connector is a remote MCP server.
- Ad account
- The container Meta bills and reports on. Campaigns, creatives and access roles hang off one ad account, and its ID is written act_ followed by a number.
- Campaign, ad set and ad
- Meta's three levels. The campaign holds the objective, the ad set holds budget, schedule, bidding and audience, and the ad holds the creative.
- Attribution window
- How long after a click or a view a conversion still counts for an ad, for example 7 days after a click and 1 day after a view.
- Insights API
- The reporting part of the Marketing API. It needs the ads_read permission and is available on the ad account, campaign, ad set and ad.
- Dynamic client registration
- A way for an OAuth client to register itself with the authorization server. Hermes Agent uses it when the server does not support a Client ID Metadata Document, and the Ryze AI connector supports only this method.
Sources: Marketing API overview, Insights API, Ad account reference, Hermes Agent MCP documentation. Checked November 14, 2026.
Frequently asked questions
How do I connect Hermes Agent to Meta Ads?
Link Meta Ads in Ryze AI, add a ryze entry with the URL https://connector.get-ryze.ai/mcp and auth: oauth under mcp_servers in ~/.hermes/config.yaml, run hermes mcp login ryze and click Allow connection. Then start a new session or run /reload-mcp and ask for a Meta Ads report.
Is there a Meta Ads MCP connector for Hermes Agent?
Yes, the Ryze AI connector at https://connector.get-ryze.ai/mcp. It is a remote MCP server with 10 Meta Ads tools, and Hermes Agent supports remote HTTP servers with OAuth. Meta also hosts its own ads MCP server at https://mcp.facebook.com/ads in open beta, and its pages do not name Hermes Agent.
Can Hermes Agent use Meta's own ads MCP server?
Probably, because Meta says the server works with any MCP-compatible AI agent and Hermes Agent supports remote HTTP servers with OAuth. Meta's pages name ChatGPT, Claude and Perplexity as supported and give steps for Claude Code and ChatGPT, and this was not tested in Hermes Agent. Not all ad accounts have access yet because of a phased rollout.
Is this the same as the Composio setup in the older Ryze AI post?
No. The older post, How to connect Google and Meta Ads with Hermes Agent, sets up Composio with its own endpoint and API key header. This guide uses the Ryze AI connector, which has its own sign-in and its own 10 Meta Ads tools. Both can sit in config.yaml under different server names.
Does Hermes Agent need a paid plan for MCP?
No. Hermes Agent is open source under the MIT license per its GitHub repository and self-hosted. The Ryze AI side needs a plan or trial for the Meta Ads tools: Paid Ads at $89 per month with a 7-day free trial.
Should I use OAuth or an API key?
Use OAuth when you can open a browser, because hermes mcp login ryze handles the sign-in and Hermes Agent refreshes the tokens. Use a Ryze AI API key in a bearer header for servers and scripts where nobody can click Allow connection. The key works on the /mcp endpoint only.
Can Hermes Agent change my Meta ad account?
Yes, when the connected Meta login has a role that may edit ads, because 2 of the 10 tools write and 1 deletes. The Ryze AI help center asks for Admin to allow changes. To have Hermes Agent ask first, set trust: untrusted on the ryze entry.
How do I make it read-only?
Connect a Meta login that only has read access, which is a hard guarantee. In Hermes Agent you can also list the 7 read tools under tools.include on the ryze entry, which hides the write and delete tools from the agent but is not enforced by Meta.
Does it work on a headless server or a VPS?
Yes, with an extra step for the sign-in. Paste the redirect URL back at the prompt that hermes mcp login prints, or use a Ryze AI API key, which avoids the browser entirely.
Can I use several ad accounts or Meta logins?
Yes. One Meta login reaches every ad account it can access, and several logins can be connected to one workspace with View > Add one more account. Name the account in your prompt, or pass connection_id to pick a login over MCP.
Can Hermes Agent post to my Facebook Page or read its comments?
No. The Ryze AI Meta app does not hold pages_manage_posts, instagram_content_publish or pages_read_user_content, so organic posts and Page comments are out of reach. The connector manages ads, not organic content.
Why do the Meta Ads tools not show up in Hermes Agent?
Start a new session or run /reload-mcp, then run hermes mcp test ryze. Check that no tools.include or tools.exclude filter hides them and that the entry is not set to enabled: false. Also confirm that Meta Ads shows Connected in Ryze AI.
How much does it cost?
Adding the connector is free. The Meta Ads tools need a Ryze AI plan or trial: Paid Ads is $89 per month with a 7-day free trial, Agency is $279 per month, and annual billing takes 30% off the first year. Hermes Agent itself is free software, and Meta says it charges nothing extra to connect its own server.
How do I disconnect Meta Ads from Hermes Agent?
Set enabled: false on the ryze entry or delete it from config.yaml, and delete ~/.hermes/mcp-tokens/ryze.json. To cut Meta access as well, disconnect the login on the Meta Ads card in Ryze AI.
Sources
- Hermes Agent MCP documentation
- NousResearch/hermes-agent on GitHub
- Meta ads MCP server overview
- Meta ads MCP server get started
- Meta ads MCP server (marketing page)
- Meta ads AI connectors announcement
- Meta Ads CLI overview
- Marketing API rate limiting
- Insights API best practices
- Meta permissions reference
- Meta ad account roles (help)
- Marketing API authorization and access tiers
- Marketing API versions
- Composio Meta Ads toolkit
- Pipeboard Meta Ads MCP
- Windsor.ai Facebook Ads MCP
- Ryze AI help center: Meta Ads
Checked November 14, 2026.