> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gumloop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Meta Ads

> Read and analyze your Meta (Facebook & Instagram) advertising with AI — ad accounts, campaigns, ad sets, ads, creatives, and performance insights.

Meta Ads is the advertising platform for Facebook and Instagram. The Meta Ads MCP server connects to the Meta Marketing API so your agents can inspect your ad accounts and pull performance data using natural language.

<Info>
  This integration is **read-only**. It is built for reporting and analysis — listing and inspecting your ad accounts, campaigns, ad sets, ads, and creatives, and pulling performance insights. It does not create, pause, or edit anything in Meta Ads.
</Info>

## What Can It Do?

* **Browse your ad hierarchy** — ad accounts, campaigns, ad sets, ads, and creatives
* **Filter by status** when listing campaigns, ad sets, and ads
* **Pull performance insights** — spend, impressions, reach, clicks, CPC, CPM, CTR, conversions, and ROAS
* **Report over any time range** using date presets (last 7/14/28/30/90 days, this/last month, this quarter, and more)
* **Analyze at any level** — insights for a whole ad account, or a single campaign, ad set, or ad

## Where to Use It

### In Agents (Recommended)

Add Meta Ads as a tool to any agent. The agent can then explore your advertising data conversationally, choosing the right actions based on context.

<video autoPlay muted loop playsInline className="w-full rounded-xl border border-pink-200 dark:border-pink-800" src="https://mintcdn.com/agenthub/B_VSlOOQHPvtlTyv/images/Connect_MCP_Tool_Agents.mp4?fit=max&auto=format&n=B_VSlOOQHPvtlTyv&q=85&s=f297b8516c66ea5697f7d5ef1cce934a" data-path="images/Connect_MCP_Tool_Agents.mp4" />

**To add an MCP tool to your agent:**

1. Open your agent's configuration
2. Click **Add tools** → **Connect an app with MCP**
3. Search for Meta Ads and select it
4. Authenticate with your Meta account

<Tip>
  You can control which tools your agent has access to. After adding the integration, click on it to enable or disable specific tools based on what your agent needs.
</Tip>

### In Workflows (Via Agent Node)

For automated pipelines, use an [Agent Node](/core-concepts/agent_node) with Meta Ads tools. This gives you the flexibility of an agent within a deterministic workflow — for example, a scheduled workflow that pulls yesterday's spend and posts it to Slack.

### As a Custom MCP Node

You can also create a standalone MCP node for a specific action. This generates a reusable node that performs one task, useful when you need the same read repeatedly in workflows.

**To create a custom MCP node:**

1. Go to your node library and search for Meta Ads
2. Click **Create a node with AI**
3. Describe the specific action you want (e.g., "Get last 30 days of spend and clicks for a campaign")
4. Test the node and save it for reuse

<Info>
  Custom MCP nodes are single-purpose by design. For tasks that require multiple steps or dynamic decision-making, use an agent instead.
</Info>

## Authentication

Meta Ads uses OAuth. When you connect the integration, you authorize Gumloop with two read-only permissions:

| Scope           | What it grants                                           |
| --------------- | -------------------------------------------------------- |
| `ads_read`      | Read ad accounts, campaigns, ad sets, ads, and creatives |
| `read_insights` | Read performance insights and reporting data             |

These read-only scopes cover every tool below. Management scopes (which would allow creating or pausing ads) are not requested.

## Available Tools

| Tool                  | Description                                                                                                             |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **List Ad Accounts**  | List the ad accounts the authenticated user can access                                                                  |
| **Get Ad Account**    | Get details for a single ad account by ID                                                                               |
| **List Campaigns**    | List campaigns in an ad account, optionally filtered by status                                                          |
| **Get Campaign**      | Get details for a single campaign by ID                                                                                 |
| **List Ad Sets**      | List ad sets in an ad account, optionally scoped to one campaign or filtered by status                                  |
| **Get Ad Set**        | Get details for a single ad set by ID                                                                                   |
| **List Ads**          | List ads in an ad account, optionally scoped to one campaign or ad set or filtered by status                            |
| **Get Ad**            | Get details for a single ad by ID                                                                                       |
| **List Ad Creatives** | List the ad creatives stored in an ad account's creative library                                                        |
| **Get Ad Creative**   | Get details for a single ad creative by ID                                                                              |
| **Get Insights**      | Get performance insights (spend, impressions, clicks, conversions, and more) for an ad account, campaign, ad set, or ad |

### Insights: metrics and time ranges

**Get Insights** returns metrics such as `spend`, `impressions`, `reach`, `frequency`, `clicks`, `cpc`, `cpm`, `ctr`, `conversions`, `cost_per_conversion`, and `purchase_roas`. When you don't specify metrics, it returns a sensible default set (spend, impressions, clicks, CPC, CTR, and actions).

You can report over a preset date range, including:

`today` · `yesterday` · `last_7d` · `last_14d` · `last_28d` · `last_30d` · `last_90d` · `this_week_mon_today` · `last_week_mon_sun` · `this_month` · `last_month` · `this_quarter` · `maximum`

## Example Prompts

Use these with your agent or in the Agent Node:

**List your accounts:**

```text theme={"dark"}
List my Meta ad accounts
```

**Campaign overview:**

```text theme={"dark"}
List the active campaigns in my main ad account
```

**Performance report:**

```text theme={"dark"}
Get spend, clicks, and CTR for my top campaign over the last 30 days
```

**Spend check:**

```text theme={"dark"}
Show total spend across my ad account for last month
```

**ROAS analysis:**

```text theme={"dark"}
What was the purchase ROAS for each ad set in my prospecting campaign last 7 days?
```

**Creative lookup:**

```text theme={"dark"}
List the ad creatives in my ad account and show what each ad is running
```

## Troubleshooting

| Issue                                   | Solution                                                                                                                                            |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| Agent asks you to create or pause an ad | This integration is read-only. Use it for reporting and analysis; make changes in Meta Ads Manager.                                                 |
| Agent not finding the right account     | Ask it to "List my ad accounts" first, then reference the account by name or ID.                                                                    |
| No data returned for a time range       | Make sure the campaign was running in that window, and try a wider preset like `last_30d`.                                                          |
| Action not completing                   | Check that you've authenticated and that your Meta account has access to the ad account.                                                            |
| Unexpected results                      | The agent may chain multiple tools (e.g., listing campaigns first, then pulling insights). Review the agent's reasoning to understand its approach. |
| Tool not available                      | Verify the tool is [enabled in your agent's MCP configuration](/core-concepts/agents#tool-management-and-approvals)                                 |

<Tip>
  Agents chain calls automatically. Asking "Which campaign spent the most last week?" will list campaigns, pull insights for each, then compare — all without you specifying IDs.
</Tip>

## Need Help?

* [Agents documentation](/core-concepts/agents) for setup and best practices
* [Agent Node guide](/core-concepts/agent_node) for workflow integration
* Need help? [Reach out to us](https://portal.usepylon.com/gumloop/forms/help)
* Contact [support@gumloop.com](mailto:support@gumloop.com) for assistance