meta-ads-mcp 0.3.2__tar.gz → 0.3.5__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (42) hide show
  1. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/PKG-INFO +104 -34
  2. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/README.md +102 -32
  3. meta_ads_mcp-0.3.5/brands/injurypayouts.com/120221013820800183_76c8b7fd0c627bce0d6ad833682f45e5.jpg +0 -0
  4. meta_ads_mcp-0.3.5/brands/injurypayouts.com/120221013841190183_cc1ff1ad28a037f397fd0e1636e8239a.jpg +0 -0
  5. meta_ads_mcp-0.3.5/brands/injurypayouts.com/120221013863110183_76f042047ce288bfbf9e103ffa10c50f.jpg +0 -0
  6. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/__init__.py +1 -1
  7. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/__init__.py +4 -0
  8. meta_ads_mcp-0.3.5/meta_ads_mcp/core/ads.py +819 -0
  9. meta_ads_mcp-0.3.5/meta_ads_mcp/core/ads_library.py +69 -0
  10. meta_ads_mcp-0.3.5/meta_ads_mcp/core/budget_schedules.py +71 -0
  11. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/campaigns.py +5 -2
  12. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/pyproject.toml +2 -2
  13. meta_ads_mcp-0.3.2/meta_ads_mcp/core/ads.py +0 -357
  14. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/.gitignore +0 -0
  15. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/Dockerfile +0 -0
  16. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/LICENSE +0 -0
  17. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/META_API_NOTES.md +0 -0
  18. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/debug_meta_api_tool.py +0 -0
  19. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/debug_token_flow.py +0 -0
  20. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/future_improvements.md +0 -0
  21. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/images/meta-ads-example.png +0 -0
  22. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta-ads-mcp +0 -0
  23. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_auth.sh +0 -0
  24. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/__main__.py +0 -0
  25. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/api.py +0 -0
  26. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/accounts.py +0 -0
  27. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/adsets.py +0 -0
  28. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/api.py +0 -0
  29. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/auth.py +0 -0
  30. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/authentication.py +0 -0
  31. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/callback_server.py +0 -0
  32. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/insights.py +0 -0
  33. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/pipeboard_auth.py +0 -0
  34. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/resources.py +0 -0
  35. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/server.py +0 -0
  36. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_ads_mcp/core/utils.py +0 -0
  37. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/meta_auth_test.sh +0 -0
  38. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/requirements.txt +0 -0
  39. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/setup.py +0 -0
  40. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/smithery.yaml +0 -0
  41. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/test_meta_ads_auth.py +0 -0
  42. {meta_ads_mcp-0.3.2 → meta_ads_mcp-0.3.5}/test_pipeboard_auth.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: meta-ads-mcp
3
- Version: 0.3.2
3
+ Version: 0.3.5
4
4
  Summary: Model Calling Protocol (MCP) plugin for interacting with Meta Ads API
5
5
  Project-URL: Homepage, https://github.com/nictuku/meta-ads-mcp
6
6
  Project-URL: Bug Tracker, https://github.com/nictuku/meta-ads-mcp/issues
@@ -11,7 +11,7 @@ Keywords: ads,api,claude,facebook,mcp,meta
11
11
  Classifier: License :: OSI Approved :: MIT License
12
12
  Classifier: Operating System :: OS Independent
13
13
  Classifier: Programming Language :: Python :: 3
14
- Requires-Python: >=3.11
14
+ Requires-Python: >=3.9.6
15
15
  Requires-Dist: httpx>=0.26.0
16
16
  Requires-Dist: mcp[cli]>=1.6.0
17
17
  Requires-Dist: pathlib>=1.0.1
@@ -27,11 +27,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
27
27
 
28
28
  > **DISCLAIMER:** This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs according to their terms of service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.
29
29
 
30
- <a href="https://glama.ai/mcp/servers/@pipeboard-co/meta-ads-mcp">
31
- <img width="380" height="200" src="https://glama.ai/mcp/servers/@pipeboard-co/meta-ads-mcp/badge" alt="Meta Ads MCP server" />
32
- </a>
33
-
34
- Screenshot: using an LLM to understand your ad performance.
30
+ **Screenshot**: Using an LLM to understand your ad performance:
35
31
 
36
32
  ![Meta Ads MCP in action: Visualize ad performance metrics and creative details directly in Claude or your favorite MCP client, with rich insights about campaign reach, engagement, and costs](./images/meta-ads-example.png)
37
33
 
@@ -94,7 +90,7 @@ python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
94
90
  Before using the MCP server, you'll need to set up a Meta Developer App:
95
91
 
96
92
  1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
97
- 2. Choose the "Consumer" app type
93
+ 2. Choose the "Business" app type
98
94
  3. In your app settings, add the "Marketing API" product
99
95
  4. Configure your app's OAuth redirect URI to include `http://localhost:8888/callback`
100
96
  5. Note your App ID (Client ID) for use with the MCP
@@ -129,7 +125,14 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
129
125
  - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
130
126
  - Returns: Detailed information about the specified account
131
127
 
132
- 3. `mcp_meta_ads_get_campaigns`
128
+ 3. `mcp_meta_ads_get_account_pages`
129
+ - Get pages associated with a Meta Ads account
130
+ - Inputs:
131
+ - `access_token` (optional): Meta API access token (will use cached token if not provided)
132
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX) or "me" for the current user's pages
133
+ - Returns: List of pages associated with the account, useful for ad creation and management
134
+
135
+ 4. `mcp_meta_ads_get_campaigns`
133
136
  - Get campaigns for a Meta Ads account with optional filtering
134
137
  - Inputs:
135
138
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -138,14 +141,14 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
138
141
  - `status_filter`: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
139
142
  - Returns: List of campaigns matching the criteria
140
143
 
141
- 4. `mcp_meta_ads_get_campaign_details`
144
+ 5. `mcp_meta_ads_get_campaign_details`
142
145
  - Get detailed information about a specific campaign
143
146
  - Inputs:
144
147
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
145
148
  - `campaign_id`: Meta Ads campaign ID
146
149
  - Returns: Detailed information about the specified campaign
147
150
 
148
- 5. `mcp_meta_ads_create_campaign`
151
+ 6. `mcp_meta_ads_create_campaign`
149
152
  - Create a new campaign in a Meta Ads account
150
153
  - Inputs:
151
154
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -158,7 +161,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
158
161
  - `lifetime_budget`: Lifetime budget in account currency (in cents)
159
162
  - Returns: Confirmation with new campaign details
160
163
 
161
- 6. `mcp_meta_ads_get_adsets`
164
+ 7. `mcp_meta_ads_get_adsets`
162
165
  - Get ad sets for a Meta Ads account with optional filtering by campaign
163
166
  - Inputs:
164
167
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -167,45 +170,101 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
167
170
  - `campaign_id`: Optional campaign ID to filter by
168
171
  - Returns: List of ad sets matching the criteria
169
172
 
170
- 7. `mcp_meta_ads_get_adset_details`
173
+ 8. `mcp_meta_ads_get_adset_details`
171
174
  - Get detailed information about a specific ad set
172
175
  - Inputs:
173
176
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
174
177
  - `adset_id`: Meta Ads ad set ID
175
178
  - Returns: Detailed information about the specified ad set
176
179
 
177
- 8. `mcp_meta_ads_get_ads`
178
- - Get ads for a Meta Ads account with optional filtering
180
+ 9. `mcp_meta_ads_create_adset`
181
+ - Create a new ad set in a Meta Ads account
179
182
  - Inputs:
180
- - `access_token` (optional): Meta API access token (will use cached token if not provided)
181
183
  - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
182
- - `limit`: Maximum number of ads to return (default: 10)
183
- - `campaign_id`: Optional campaign ID to filter by
184
- - `adset_id`: Optional ad set ID to filter by
185
- - Returns: List of ads matching the criteria
186
-
187
- 9. `mcp_meta_ads_get_ad_details`
188
- - Get detailed information about a specific ad
189
- - Inputs:
190
- - `access_token` (optional): Meta API access token (will use cached token if not provided)
191
- - `ad_id`: Meta Ads ad ID
192
- - Returns: Detailed information about the specified ad
184
+ - `campaign_id`: Meta Ads campaign ID this ad set belongs to
185
+ - `name`: Ad set name
186
+ - `status`: Initial ad set status (default: PAUSED)
187
+ - `daily_budget`: Daily budget in account currency (in cents) as a string
188
+ - `lifetime_budget`: Lifetime budget in account currency (in cents) as a string
189
+ - `targeting`: Targeting specifications (e.g., age, location, interests)
190
+ - `optimization_goal`: Conversion optimization goal (e.g., 'LINK_CLICKS')
191
+ - `billing_event`: How you're charged (e.g., 'IMPRESSIONS')
192
+ - `bid_amount`: Bid amount in account currency (in cents)
193
+ - `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST')
194
+ - `start_time`, `end_time`: Optional start/end times (ISO 8601)
195
+ - `access_token` (optional): Meta API access token
196
+ - Returns: Confirmation with new ad set details
197
+
198
+ 10. `mcp_meta_ads_get_ads`
199
+ - Get ads for a Meta Ads account with optional filtering
200
+ - Inputs:
201
+ - `access_token` (optional): Meta API access token (will use cached token if not provided)
202
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
203
+ - `limit`: Maximum number of ads to return (default: 10)
204
+ - `campaign_id`: Optional campaign ID to filter by
205
+ - `adset_id`: Optional ad set ID to filter by
206
+ - Returns: List of ads matching the criteria
207
+
208
+ 11. `mcp_meta_ads_create_ad`
209
+ - Create a new ad with an existing creative
210
+ - Inputs:
211
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
212
+ - `name`: Ad name
213
+ - `adset_id`: Ad set ID where this ad will be placed
214
+ - `creative_id`: ID of an existing creative to use
215
+ - `status`: Initial ad status (default: PAUSED)
216
+ - `bid_amount`: Optional bid amount (in cents)
217
+ - `tracking_specs`: Optional tracking specifications
218
+ - `access_token` (optional): Meta API access token
219
+ - Returns: Confirmation with new ad details
220
+
221
+ 12. `mcp_meta_ads_get_ad_details`
222
+ - Get detailed information about a specific ad
223
+ - Inputs:
224
+ - `access_token` (optional): Meta API access token (will use cached token if not provided)
225
+ - `ad_id`: Meta Ads ad ID
226
+ - Returns: Detailed information about the specified ad
193
227
 
194
- 10. `mcp_meta_ads_get_ad_creatives`
228
+ 13. `mcp_meta_ads_get_ad_creatives`
195
229
  - Get creative details for a specific ad
196
230
  - Inputs:
197
231
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
198
232
  - `ad_id`: Meta Ads ad ID
199
233
  - Returns: Creative details including text, images, and URLs
200
234
 
201
- 11. `mcp_meta_ads_get_ad_image`
235
+ 14. `mcp_meta_ads_create_ad_creative`
236
+ - Create a new ad creative using an uploaded image hash
237
+ - Inputs:
238
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
239
+ - `name`: Creative name
240
+ - `image_hash`: Hash of the uploaded image
241
+ - `page_id`: Facebook Page ID for the ad
242
+ - `link_url`: Destination URL
243
+ - `message`: Ad copy/text
244
+ - `headline`: Ad headline
245
+ - `description`: Ad description
246
+ - `call_to_action_type`: CTA button type (e.g., 'LEARN_MORE')
247
+ - `instagram_actor_id`: Optional Instagram account ID
248
+ - `access_token` (optional): Meta API access token
249
+ - Returns: Confirmation with new creative details
250
+
251
+ 15. `mcp_meta_ads_upload_ad_image`
252
+ - Upload an image to use in Meta Ads creatives
253
+ - Inputs:
254
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
255
+ - `image_path`: Path to the image file to upload
256
+ - `name`: Optional name for the image
257
+ - `access_token` (optional): Meta API access token
258
+ - Returns: JSON response with image details including hash
259
+
260
+ 16. `mcp_meta_ads_get_ad_image`
202
261
  - Get, download, and visualize a Meta ad image in one step
203
262
  - Inputs:
204
263
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
205
264
  - `ad_id`: Meta Ads ad ID
206
265
  - Returns: The ad image ready for direct visual analysis
207
266
 
208
- 12. `mcp_meta_ads_update_ad`
267
+ 17. `mcp_meta_ads_update_ad`
209
268
  - Update an ad with new settings
210
269
  - Inputs:
211
270
  - `ad_id`: Meta Ads ad ID
@@ -214,7 +273,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
214
273
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
215
274
  - Returns: Confirmation with updated ad details and a confirmation link
216
275
 
217
- 13. `mcp_meta_ads_update_adset`
276
+ 18. `mcp_meta_ads_update_adset`
218
277
  - Update an ad set with new settings including frequency caps
219
278
  - Inputs:
220
279
  - `adset_id`: Meta Ads ad set ID
@@ -226,7 +285,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
226
285
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
227
286
  - Returns: Confirmation with updated ad set details and a confirmation link
228
287
 
229
- 14. `mcp_meta_ads_get_insights`
288
+ 19. `mcp_meta_ads_get_insights`
230
289
  - Get performance insights for a campaign, ad set, ad or account
231
290
  - Inputs:
232
291
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -236,7 +295,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
236
295
  - `level`: Level of aggregation (ad, adset, campaign, account)
237
296
  - Returns: Performance metrics for the specified object
238
297
 
239
- 15. `mcp_meta_ads_debug_image_download`
298
+ 20. `mcp_meta_ads_debug_image_download`
240
299
  - Debug image download issues and report detailed diagnostics
241
300
  - Inputs:
242
301
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -244,12 +303,23 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
244
303
  - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
245
304
  - Returns: Diagnostic information about image download attempts
246
305
 
247
- 16. `mcp_meta_ads_get_login_link`
306
+ 21. `mcp_meta_ads_get_login_link`
248
307
  - Get a clickable login link for Meta Ads authentication
249
308
  - Inputs:
250
309
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
251
310
  - Returns: A clickable resource link for Meta authentication
252
311
 
312
+ 22. `mcp_meta-ads_create_budget_schedule`
313
+ - Create a budget schedule for a Meta Ads campaign.
314
+ - Inputs:
315
+ - `campaign_id`: Meta Ads campaign ID.
316
+ - `budget_value`: Amount of budget increase.
317
+ - `budget_value_type`: Type of budget value ("ABSOLUTE" or "MULTIPLIER").
318
+ - `time_start`: Unix timestamp for when the high demand period should start.
319
+ - `time_end`: Unix timestamp for when the high demand period should end.
320
+ - `access_token` (optional): Meta API access token.
321
+ - Returns: JSON string with the ID of the created budget schedule or an error message.
322
+
253
323
  ## Authentication
254
324
 
255
325
  The Meta Ads MCP uses Meta's OAuth 2.0 authentication flow, designed for desktop apps:
@@ -4,11 +4,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
4
4
 
5
5
  > **DISCLAIMER:** This is an unofficial third-party tool and is not associated with, endorsed by, or affiliated with Meta in any way. This project is maintained independently and uses Meta's public APIs according to their terms of service. Meta, Facebook, Instagram, and other Meta brand names are trademarks of their respective owners.
6
6
 
7
- <a href="https://glama.ai/mcp/servers/@pipeboard-co/meta-ads-mcp">
8
- <img width="380" height="200" src="https://glama.ai/mcp/servers/@pipeboard-co/meta-ads-mcp/badge" alt="Meta Ads MCP server" />
9
- </a>
10
-
11
- Screenshot: using an LLM to understand your ad performance.
7
+ **Screenshot**: Using an LLM to understand your ad performance:
12
8
 
13
9
  ![Meta Ads MCP in action: Visualize ad performance metrics and creative details directly in Claude or your favorite MCP client, with rich insights about campaign reach, engagement, and costs](./images/meta-ads-example.png)
14
10
 
@@ -71,7 +67,7 @@ python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
71
67
  Before using the MCP server, you'll need to set up a Meta Developer App:
72
68
 
73
69
  1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
74
- 2. Choose the "Consumer" app type
70
+ 2. Choose the "Business" app type
75
71
  3. In your app settings, add the "Marketing API" product
76
72
  4. Configure your app's OAuth redirect URI to include `http://localhost:8888/callback`
77
73
  5. Note your App ID (Client ID) for use with the MCP
@@ -106,7 +102,14 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
106
102
  - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
107
103
  - Returns: Detailed information about the specified account
108
104
 
109
- 3. `mcp_meta_ads_get_campaigns`
105
+ 3. `mcp_meta_ads_get_account_pages`
106
+ - Get pages associated with a Meta Ads account
107
+ - Inputs:
108
+ - `access_token` (optional): Meta API access token (will use cached token if not provided)
109
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX) or "me" for the current user's pages
110
+ - Returns: List of pages associated with the account, useful for ad creation and management
111
+
112
+ 4. `mcp_meta_ads_get_campaigns`
110
113
  - Get campaigns for a Meta Ads account with optional filtering
111
114
  - Inputs:
112
115
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -115,14 +118,14 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
115
118
  - `status_filter`: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
116
119
  - Returns: List of campaigns matching the criteria
117
120
 
118
- 4. `mcp_meta_ads_get_campaign_details`
121
+ 5. `mcp_meta_ads_get_campaign_details`
119
122
  - Get detailed information about a specific campaign
120
123
  - Inputs:
121
124
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
122
125
  - `campaign_id`: Meta Ads campaign ID
123
126
  - Returns: Detailed information about the specified campaign
124
127
 
125
- 5. `mcp_meta_ads_create_campaign`
128
+ 6. `mcp_meta_ads_create_campaign`
126
129
  - Create a new campaign in a Meta Ads account
127
130
  - Inputs:
128
131
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -135,7 +138,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
135
138
  - `lifetime_budget`: Lifetime budget in account currency (in cents)
136
139
  - Returns: Confirmation with new campaign details
137
140
 
138
- 6. `mcp_meta_ads_get_adsets`
141
+ 7. `mcp_meta_ads_get_adsets`
139
142
  - Get ad sets for a Meta Ads account with optional filtering by campaign
140
143
  - Inputs:
141
144
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -144,45 +147,101 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
144
147
  - `campaign_id`: Optional campaign ID to filter by
145
148
  - Returns: List of ad sets matching the criteria
146
149
 
147
- 7. `mcp_meta_ads_get_adset_details`
150
+ 8. `mcp_meta_ads_get_adset_details`
148
151
  - Get detailed information about a specific ad set
149
152
  - Inputs:
150
153
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
151
154
  - `adset_id`: Meta Ads ad set ID
152
155
  - Returns: Detailed information about the specified ad set
153
156
 
154
- 8. `mcp_meta_ads_get_ads`
155
- - Get ads for a Meta Ads account with optional filtering
157
+ 9. `mcp_meta_ads_create_adset`
158
+ - Create a new ad set in a Meta Ads account
156
159
  - Inputs:
157
- - `access_token` (optional): Meta API access token (will use cached token if not provided)
158
160
  - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
159
- - `limit`: Maximum number of ads to return (default: 10)
160
- - `campaign_id`: Optional campaign ID to filter by
161
- - `adset_id`: Optional ad set ID to filter by
162
- - Returns: List of ads matching the criteria
163
-
164
- 9. `mcp_meta_ads_get_ad_details`
165
- - Get detailed information about a specific ad
166
- - Inputs:
167
- - `access_token` (optional): Meta API access token (will use cached token if not provided)
168
- - `ad_id`: Meta Ads ad ID
169
- - Returns: Detailed information about the specified ad
161
+ - `campaign_id`: Meta Ads campaign ID this ad set belongs to
162
+ - `name`: Ad set name
163
+ - `status`: Initial ad set status (default: PAUSED)
164
+ - `daily_budget`: Daily budget in account currency (in cents) as a string
165
+ - `lifetime_budget`: Lifetime budget in account currency (in cents) as a string
166
+ - `targeting`: Targeting specifications (e.g., age, location, interests)
167
+ - `optimization_goal`: Conversion optimization goal (e.g., 'LINK_CLICKS')
168
+ - `billing_event`: How you're charged (e.g., 'IMPRESSIONS')
169
+ - `bid_amount`: Bid amount in account currency (in cents)
170
+ - `bid_strategy`: Bid strategy (e.g., 'LOWEST_COST')
171
+ - `start_time`, `end_time`: Optional start/end times (ISO 8601)
172
+ - `access_token` (optional): Meta API access token
173
+ - Returns: Confirmation with new ad set details
174
+
175
+ 10. `mcp_meta_ads_get_ads`
176
+ - Get ads for a Meta Ads account with optional filtering
177
+ - Inputs:
178
+ - `access_token` (optional): Meta API access token (will use cached token if not provided)
179
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
180
+ - `limit`: Maximum number of ads to return (default: 10)
181
+ - `campaign_id`: Optional campaign ID to filter by
182
+ - `adset_id`: Optional ad set ID to filter by
183
+ - Returns: List of ads matching the criteria
184
+
185
+ 11. `mcp_meta_ads_create_ad`
186
+ - Create a new ad with an existing creative
187
+ - Inputs:
188
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
189
+ - `name`: Ad name
190
+ - `adset_id`: Ad set ID where this ad will be placed
191
+ - `creative_id`: ID of an existing creative to use
192
+ - `status`: Initial ad status (default: PAUSED)
193
+ - `bid_amount`: Optional bid amount (in cents)
194
+ - `tracking_specs`: Optional tracking specifications
195
+ - `access_token` (optional): Meta API access token
196
+ - Returns: Confirmation with new ad details
197
+
198
+ 12. `mcp_meta_ads_get_ad_details`
199
+ - Get detailed information about a specific ad
200
+ - Inputs:
201
+ - `access_token` (optional): Meta API access token (will use cached token if not provided)
202
+ - `ad_id`: Meta Ads ad ID
203
+ - Returns: Detailed information about the specified ad
170
204
 
171
- 10. `mcp_meta_ads_get_ad_creatives`
205
+ 13. `mcp_meta_ads_get_ad_creatives`
172
206
  - Get creative details for a specific ad
173
207
  - Inputs:
174
208
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
175
209
  - `ad_id`: Meta Ads ad ID
176
210
  - Returns: Creative details including text, images, and URLs
177
211
 
178
- 11. `mcp_meta_ads_get_ad_image`
212
+ 14. `mcp_meta_ads_create_ad_creative`
213
+ - Create a new ad creative using an uploaded image hash
214
+ - Inputs:
215
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
216
+ - `name`: Creative name
217
+ - `image_hash`: Hash of the uploaded image
218
+ - `page_id`: Facebook Page ID for the ad
219
+ - `link_url`: Destination URL
220
+ - `message`: Ad copy/text
221
+ - `headline`: Ad headline
222
+ - `description`: Ad description
223
+ - `call_to_action_type`: CTA button type (e.g., 'LEARN_MORE')
224
+ - `instagram_actor_id`: Optional Instagram account ID
225
+ - `access_token` (optional): Meta API access token
226
+ - Returns: Confirmation with new creative details
227
+
228
+ 15. `mcp_meta_ads_upload_ad_image`
229
+ - Upload an image to use in Meta Ads creatives
230
+ - Inputs:
231
+ - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
232
+ - `image_path`: Path to the image file to upload
233
+ - `name`: Optional name for the image
234
+ - `access_token` (optional): Meta API access token
235
+ - Returns: JSON response with image details including hash
236
+
237
+ 16. `mcp_meta_ads_get_ad_image`
179
238
  - Get, download, and visualize a Meta ad image in one step
180
239
  - Inputs:
181
240
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
182
241
  - `ad_id`: Meta Ads ad ID
183
242
  - Returns: The ad image ready for direct visual analysis
184
243
 
185
- 12. `mcp_meta_ads_update_ad`
244
+ 17. `mcp_meta_ads_update_ad`
186
245
  - Update an ad with new settings
187
246
  - Inputs:
188
247
  - `ad_id`: Meta Ads ad ID
@@ -191,7 +250,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
191
250
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
192
251
  - Returns: Confirmation with updated ad details and a confirmation link
193
252
 
194
- 13. `mcp_meta_ads_update_adset`
253
+ 18. `mcp_meta_ads_update_adset`
195
254
  - Update an ad set with new settings including frequency caps
196
255
  - Inputs:
197
256
  - `adset_id`: Meta Ads ad set ID
@@ -203,7 +262,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
203
262
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
204
263
  - Returns: Confirmation with updated ad set details and a confirmation link
205
264
 
206
- 14. `mcp_meta_ads_get_insights`
265
+ 19. `mcp_meta_ads_get_insights`
207
266
  - Get performance insights for a campaign, ad set, ad or account
208
267
  - Inputs:
209
268
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -213,7 +272,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
213
272
  - `level`: Level of aggregation (ad, adset, campaign, account)
214
273
  - Returns: Performance metrics for the specified object
215
274
 
216
- 15. `mcp_meta_ads_debug_image_download`
275
+ 20. `mcp_meta_ads_debug_image_download`
217
276
  - Debug image download issues and report detailed diagnostics
218
277
  - Inputs:
219
278
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -221,12 +280,23 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
221
280
  - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
222
281
  - Returns: Diagnostic information about image download attempts
223
282
 
224
- 16. `mcp_meta_ads_get_login_link`
283
+ 21. `mcp_meta_ads_get_login_link`
225
284
  - Get a clickable login link for Meta Ads authentication
226
285
  - Inputs:
227
286
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
228
287
  - Returns: A clickable resource link for Meta authentication
229
288
 
289
+ 22. `mcp_meta-ads_create_budget_schedule`
290
+ - Create a budget schedule for a Meta Ads campaign.
291
+ - Inputs:
292
+ - `campaign_id`: Meta Ads campaign ID.
293
+ - `budget_value`: Amount of budget increase.
294
+ - `budget_value_type`: Type of budget value ("ABSOLUTE" or "MULTIPLIER").
295
+ - `time_start`: Unix timestamp for when the high demand period should start.
296
+ - `time_end`: Unix timestamp for when the high demand period should end.
297
+ - `access_token` (optional): Meta API access token.
298
+ - Returns: JSON string with the ID of the created budget schedule or an error message.
299
+
230
300
  ## Authentication
231
301
 
232
302
  The Meta Ads MCP uses Meta's OAuth 2.0 authentication flow, designed for desktop apps:
@@ -7,7 +7,7 @@ with the Claude LLM.
7
7
 
8
8
  from meta_ads_mcp.core.server import main
9
9
 
10
- __version__ = "0.3.2"
10
+ __version__ = "0.3.5"
11
11
 
12
12
  __all__ = [
13
13
  'get_ad_accounts',
@@ -9,6 +9,8 @@ from .insights import get_insights, debug_image_download
9
9
  from .authentication import get_login_link
10
10
  from .server import login_cli, main
11
11
  from .auth import login
12
+ from .ads_library import search_ads_archive
13
+ from .budget_schedules import create_budget_schedule
12
14
 
13
15
  __all__ = [
14
16
  'mcp_server',
@@ -31,4 +33,6 @@ __all__ = [
31
33
  'login_cli',
32
34
  'login',
33
35
  'main',
36
+ 'search_ads_archive',
37
+ 'create_budget_schedule',
34
38
  ]