ChatGPT Ads
ChatGPT Ads (OpenAI Ads) API for campaign structure and delivery reporting — read-only
17 tools available
Installation
Claude Desktop
{
"mcpServers": {
"hopkin-chatgpt-ads": {
"url": "https://chatgpt.mcp.hopkin.ai",
"headers": {
"Authorization": "Bearer YOUR_API_KEY"
}
}
}
}CLI
npm install -g @hopkin/cli
hopkin auth set-key hpk_live_...
hopkin chatgpt pingTools
ad-account
chatgpt_ads_get_ad_account Get ChatGPT Ads Account
Get details of the ChatGPT Ads account: name, status, currency, timezone, website, and review status. Each ChatGPT Ads API key is scoped to exactly one ad account, so this returns the account behind the resolved connection. Use chatgpt_ads_list_ad_accounts to see every account you can reach, and pass connection_id to pick one. Worth calling before reporting: every spend figure is in this account's currency, and every insights date bucket is a day in this account's timezone.
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
1 optional parameter
| Parameter | Type | Description |
|---|---|---|
connection_id | string | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |
auth
chatgpt_ads_check_auth_status Check ChatGPT Ads Auth Status
Check whether a ChatGPT Ads API key is connected and still accepted by the platform. Do NOT call this proactively — call the tool you actually need. Use this only after another tool fails with a permission or authentication error.
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
1 optional parameter
| Parameter | Type | Description |
|---|---|---|
connection_id | string | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |
chatgpt_ads_ping Ping ChatGPT Ads MCP Server
Health check. Returns server status, version, and timestamp. Does not contact the ChatGPT Ads API.
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
1 optional parameter
| Parameter | Type | Description |
|---|---|---|
message | string | Optional message to echo back |
ad-accounts
chatgpt_ads_list_ad_accounts List ChatGPT Ads Accounts
List the ChatGPT Ads accounts you can reach. Each ChatGPT Ads API key is scoped to exactly one ad account, and the platform has no account-listing endpoint — so this lists your connected accounts, one per API key you have added. Use the returned connection_id to target a specific account in other tools, and chatgpt_ads_get_ad_account for live details (currency, timezone, review status).
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
connections
chatgpt_ads_list_connections List ChatGPT Ads Connections
List the ChatGPT Ads connections available to you — both those you own and those shared with you by your organization. Shows each connection's display name, id, and whether it is your default.
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
set-default-connection
chatgpt_ads_set_default_connection Set Default ChatGPT Ads Connection
Set which ChatGPT Ads connection other tools use when no connection_id is passed. Call chatgpt_ads_list_connections first to get a valid connection_id — do not guess one.
| Parameter | Type | Description |
|---|---|---|
connection_id required | string | UUID of the connection to mark as the actor's default ChatGPT Ads connection. |
reason required | string | Why this tool call is needed |
rename-connection
chatgpt_ads_rename_connection Rename ChatGPT Ads Connection
Change a connection's display name. Owner-only.
| Parameter | Type | Description |
|---|---|---|
connection_id required | string | UUID of the connection to mark as the actor's default ChatGPT Ads connection. |
reason required | string | Why this tool call is needed |
share-connection
unshare-connection
revoke-connection
chatgpt_ads_revoke_connection Revoke ChatGPT Ads Connection
Remove a stored ChatGPT Ads connection. Owner-only. This deletes Hopkin's stored copy of the API key only. The key stays valid on the ChatGPT Ads platform — the API has no revocation endpoint — so tell the user to delete it in ChatGPT Ads Manager → Settings if they want it to stop working everywhere.
| Parameter | Type | Description |
|---|---|---|
connection_id required | string | UUID of the connection to mark as the actor's default ChatGPT Ads connection. |
reason required | string | Why this tool call is needed |
feedback
chatgpt_ads_developer_feedback Submit Developer Feedback
Submit feedback about missing tools, improvements, bugs, or workflow gaps in the ChatGPT Ads MCP toolset. Not for user-facing issues (auth errors, API errors). Args: feedback_type: new_tool, improvement, bug, workflow_gap title: Short description (5-200 chars) description: What is needed and why (20-2000 chars) current_workaround (optional): How you're working around the gap priority (optional): low, medium (default), high Returns: confirmation that feedback was recorded.
| Parameter | Type | Description |
|---|---|---|
feedback_type required | string | Feedback category: new_tool (request new capability), improvement (enhance existing tool), bug (report issue), workflow_gap (missing workflow) |
title required | string | Concise title summarizing the feedback |
description required | string | What is needed and why |
reason required | string | Why this tool call is needed |
3 optional parameters
| Parameter | Type | Description |
|---|---|---|
current_workaround | string | Current workaround, if any |
priority | string | Impact level: low (nice-to-have), medium (improves workflow), high (blocking issue) |
interface | string | Interface the feedback originated from: MCP (default) or CLI |
campaigns
chatgpt_ads_list_campaigns List ChatGPT Ads Campaigns
List campaigns in the ChatGPT Ads account, with optional status and name filtering. Budget and bid amounts are integer micros (1,000,000 micros = 1 unit of the account currency — see chatgpt_ads_get_ad_account). Pass campaign_ids to resolve specific campaigns by ID instead of listing. Cache-first: pass refresh: true to force a live fetch.
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
7 optional parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Maximum number of results to return (1–100). Default: 20. |
cursor | string | Opaque pagination cursor from a previous response. |
refresh | boolean | Force a fresh fetch bypassing the cache. |
campaign_ids | array | Fetch specific campaigns by ID instead of listing, e.g. ["cmpn_abc123"]. Other filters are ignored when set. |
status | array | Filter by status: active, paused or archived. Case-insensitive. Applied client-side — the API has no status filter. |
search | string | Filter by name (case-insensitive substring match). |
connection_id | string | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |
ad-groups
chatgpt_ads_list_ad_groups List ChatGPT Ads Ad Groups
List ad groups in a campaign. campaign_id is required — the ChatGPT Ads API has no account-wide ad group listing, so start from chatgpt_ads_list_campaigns and drill down. Pass ad_group_ids to resolve specific ad groups by ID instead of listing. Each returned ad group carries the campaign_id you requested; the API itself does not return it on the ad group object.
| Parameter | Type | Description |
|---|---|---|
campaign_id required | string | Campaign to list ad groups for (e.g. "cmpn_abc123"). Required — the API has no account-wide ad group listing. Get one from chatgpt_ads_list_campaigns. |
reason required | string | Why this tool call is needed |
7 optional parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Maximum number of results to return (1–100). Default: 20. |
cursor | string | Opaque pagination cursor from a previous response. |
refresh | boolean | Force a fresh fetch bypassing the cache. |
ad_group_ids | array | Fetch specific ad groups by ID instead of listing, e.g. ["adgrp_abc123"]. Other filters are ignored when set. |
status | array | Filter by status: active, paused or archived. Case-insensitive. Applied client-side — the API has no status filter. |
search | string | Filter by name (case-insensitive substring match). |
connection_id | string | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |
ads
chatgpt_ads_list_ads List ChatGPT Ads Ads
List ads in an ad group, including creative and review status. Either ad_group_id or ad_ids is required — the API has no account-wide or campaign-wide ad listing, so drill down via chatgpt_ads_list_ad_groups. An ad only delivers when it is approved AND its ad group and campaign are both active, so check review_status when an ad is not spending — filter on it with review_status: ["rejected"]. Pass ad_ids to resolve specific ads by ID without knowing their ad group. That is the way back from an insights row, which carries ad_id but no other context. Each returned ad carries the ad_group_id you requested; the API does not return it on the ad object.
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
9 optional parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Maximum number of results to return (1–100). Default: 20. |
cursor | string | Opaque pagination cursor from a previous response. |
refresh | boolean | Force a fresh fetch bypassing the cache. |
ad_group_id | string | Ad group to list ads for (e.g. "adgrp_abc123"). Required unless ad_ids is given — the API has no account-wide or campaign-wide ad listing. Get one from chatgpt_ads_list_ad_groups. |
ad_ids | array | Fetch specific ads by ID instead of listing, e.g. ["ad_abc123"]. Works without ad_group_id, and other filters are ignored when set. |
status | array | Filter by status: active, paused or archived. Case-insensitive. Applied client-side — the API has no status filter. |
review_status | array | Filter by review status: approved, in_review or rejected. Case-insensitive. An ad only delivers once approved. Applied client-side. |
search | string | Filter by name (case-insensitive substring match). |
connection_id | string | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |
insights
chatgpt_ads_get_insights Get ChatGPT Ads Insights
Delivery reporting for the ChatGPT Ads account: impressions, clicks, spend, ctr, cpc, cpm. These six are the only metrics the API exposes. This is the performance report for ChatGPT Ads — there is no separate report tool on this server. Scope vs rows: \
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
15 optional parameters
| Parameter | Type | Description |
|---|---|---|
level | string | Scope of the report. "ad_account" covers the whole account; the others need entity_id. |
entity_id | string | Campaign, ad group, or ad ID to scope to. Required unless level is "ad_account". |
aggregation_level | string | What each row represents. Must be at or below level. Defaults to level. |
time_granularity | string | Time bucket per row. "none" returns one row per entity for the whole window. Segmented requests do not support "hourly". |
date_since | string | Start date (YYYY-MM-DD) in the ad account timezone. Defaults to 30 days before date_until. |
date_until | string | End date (YYYY-MM-DD) in the ad account timezone. Defaults to today. |
fields | array | Canonical dotted field names, e.g. ["campaign.name","campaign.spend"]. Defaults to ids, name, and all six metrics for the aggregation level. |
filters | array | Filters, ANDed together. E.g. [{"field":"campaign.id","operator":"IN","value":["cmpn_1"]}]. |
sort | array | Sort order, applied before pagination. E.g. [{"field":"campaign.spend","direction":"desc"}]. |
segment | string | Extra breakdown dimension. Only available on enabled ad accounts; segmented requests cannot use hourly granularity. |
include_zero_impressions | boolean | Include entities with no impressions in the window. |
include_conversions | boolean | Also fetch attributed conversion totals per entity. Whole-window totals only, not per time bucket. Account-gated: if unavailable the delivery data is still returned. |
limit | integer | Maximum rows to return (1–2000). Default: 100. |
cursor | string | Opaque pagination cursor from a previous response. |
connection_id | string | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |
conversion-event-settings
chatgpt_ads_list_conversion_event_settings List ChatGPT Ads Conversion Event Settings
List the conversion events configured for the account — what each one counts, its attribution window, and which campaigns use it. Useful for interpreting the conversion totals returned by chatgpt_ads_get_insights. Returns a "not enabled" error on accounts without conversion tracking.
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
3 optional parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Maximum number of results to return (1–100). Default: 20. |
cursor | string | Opaque pagination cursor from a previous response. |
connection_id | string | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |
custom-audiences
chatgpt_ads_list_custom_audiences List ChatGPT Ads Custom Audiences
List the custom audiences on the account — name, status, and how many identifiers matched. Its main use is resolving identity: chatgpt_ads_list_campaigns returns targeting.custom_audiences.ids as bare IDs, so pass those to custom_audience_ids here to find out who a campaign actually targets. Audience sizes come back as privacy-bucketed ranges (e.g. "5000-10000"), never exact counts — report them as ranges.
| Parameter | Type | Description |
|---|---|---|
reason required | string | Why this tool call is needed |
4 optional parameters
| Parameter | Type | Description |
|---|---|---|
limit | integer | Maximum number of results to return (1–100). Default: 20. |
cursor | string | Opaque pagination cursor from a previous response. |
custom_audience_ids | array | Resolve specific audiences by ID instead of listing. Use this to turn the opaque IDs in a campaign's targeting.custom_audiences into names. |
connection_id | string | Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs. |