Skip to main content
Glama
Meta Ads MCP

Meta Ads MCP

by kremnyi
README.md
# Meta Ads MCP

One Node.js MCP server for the Meta Marketing API (Graph API). It has no npm dependencies.

It manages Instagram and Facebook campaigns, ad sets, ads, and creatives for one ad account. It also reads insights and Instagram media.

## Tools

| Tool | Access | Function |
| --- | --- | --- |
| `auth_status` | Read | Shows the token permissions, the token expiry, and the ad account |
| `list` | Read | Lists campaigns, ad sets, ads, creatives, audiences, pixels, and media |
| `get` | Read | Gets one object by ID |
| `insights` | Read | Gets performance data for the account, a campaign, an ad set, or an ad |
| `targeting_search` | Read | Finds interests, locations, locales, and categories |
| `create` | Write | Makes a campaign, ad set, creative, or ad |
| `update` | Write | Changes fields, for example budget, targeting, or name |
| `set_status` | Write | Sets ACTIVE, PAUSED, or ARCHIVED |
| `copy` | Write | Copies a campaign, ad set, or ad |
| `delete` | Write | Deletes a campaign, ad set, ad, or creative |

## Safety

A write can spend money. These rules apply to each write:

- The call needs an exact change summary and `user_confirmed: true`.
- `create` and `copy` always make PAUSED objects.
- `update` refuses a status change. Activation is a separate `set_status` call.
- `update`, `set_status`, `copy`, and `delete` first make sure that the object belongs to the configured ad account.

## Requirements

- Node.js 24 or later.
- The ID of a Meta ad account.
- A Meta access token for that account. The read tools need `ads_read`. The write tools need `ads_management`. Instagram media and stories also need Instagram permissions.

`auth_status` shows the granted permissions and the token expiry.

## Install

**Claude Code.** Load the directory for one session:

```sh
claude --plugin-dir /path/to/meta-ads-mcp
```

For a permanent installation, add the directory to a plugin marketplace. The plugin includes the `meta-ads` skill, which has campaign recipes.

**Other MCP clients.** Start the server on stdio:

```json
{
  "mcpServers": {
    "meta_ads": {
      "command": "node",
      "args": ["/absolute/path/to/meta-ads-mcp/scripts/server.mjs"]
    }
  }
}
```

## Configuration

The source contains no account data. Put the settings in an env file with mode `600`. See `meta-ads.env.example`.

The env file is the first of these that is set:

1. `META_ADS_ENV_FILE`
2. `$XDG_CONFIG_HOME/meta-ads/meta-ads.env`
3. `~/.config/meta-ads/meta-ads.env`

| Variable | Content |
| --- | --- |
| `META_ADS_ACCOUNT_ID` | The ad account ID, with or without the `act_` prefix |
| `META_ADS_ACCESS_TOKEN` | The access token |
| `META_ADS_API_VERSION` | Optional. The Graph API version. The default is `v23.0`. |

A variable in the environment of the server process overrides the value in the file.

The server reads the file on each call, so a new token needs no restart. The server sends the token in the `Authorization` header.

## Backup

```sh
node scripts/backup.mjs <output-directory>
```

This command makes a read-only export of the ad account as JSON files: campaigns, ad sets, ads, creatives, audiences, pixels, and insights. The output contains your account data. Do not put it in a public repository.

## Tests

```sh
npm test                      # protocol and write guards; no network, no credentials
node scripts/test.mjs --live  # read-only requests to Meta
```

## License

MIT. See `LICENSE`.

TDQS

A3.5/5.0

Scored across 10 tools

Disambiguation4/5

Most tools have clearly distinct purposes: auth_status, insights, targeting_search, copy, and set_status are unambiguous, and update is explicitly separated from set_status. The generic list/get/create/update/delete verbs operate across several object types, so boundaries are mostly clear from descriptions but not as crisp as a fully specific set.

Naming Consistency3/5

The set mixes bare imperative verbs (list, get, create, update, copy, delete), noun-style tools (insights), and compound snake_case names (auth_status, targeting_search, set_status). It is readable and all snake_case-compatible, but there is no single predictable naming pattern throughout.

Tool Count5/5

Ten tools is well-scoped for a Meta Ads management server, covering authentication, reads, writes, status changes, copying, deletion, targeting lookup, and insights without excessive surface area. Each tool appears to earn its place.

Completeness4/5

The surface covers the core campaign, ad set, ad, and creative lifecycle plus insights, targeting, and auth, so it is largely complete for the stated purpose. Minor gaps exist, such as updating creative fields explicitly and preview/review or bulk/reporting operations, but agents can work around most of them.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues