meta-ads-mcp 0.3.3__tar.gz → 0.3.6__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 (41) hide show
  1. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/PKG-INFO +87 -24
  2. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/README.md +85 -22
  3. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/__init__.py +1 -1
  4. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/api.py +1 -1
  5. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/__init__.py +2 -0
  6. meta_ads_mcp-0.3.6/meta_ads_mcp/core/budget_schedules.py +71 -0
  7. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/campaigns.py +1 -1
  8. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/pyproject.toml +2 -2
  9. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/.gitignore +0 -0
  10. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/Dockerfile +0 -0
  11. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/LICENSE +0 -0
  12. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/META_API_NOTES.md +0 -0
  13. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/brands/injurypayouts.com/120221013820800183_76c8b7fd0c627bce0d6ad833682f45e5.jpg +0 -0
  14. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/brands/injurypayouts.com/120221013841190183_cc1ff1ad28a037f397fd0e1636e8239a.jpg +0 -0
  15. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/brands/injurypayouts.com/120221013863110183_76f042047ce288bfbf9e103ffa10c50f.jpg +0 -0
  16. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/debug_meta_api_tool.py +0 -0
  17. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/debug_token_flow.py +0 -0
  18. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/future_improvements.md +0 -0
  19. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/images/meta-ads-example.png +0 -0
  20. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta-ads-mcp +0 -0
  21. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_auth.sh +0 -0
  22. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/__main__.py +0 -0
  23. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/accounts.py +0 -0
  24. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/ads.py +0 -0
  25. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/ads_library.py +0 -0
  26. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/adsets.py +0 -0
  27. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/api.py +0 -0
  28. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/auth.py +0 -0
  29. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/authentication.py +0 -0
  30. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/callback_server.py +0 -0
  31. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/insights.py +0 -0
  32. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/pipeboard_auth.py +0 -0
  33. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/resources.py +0 -0
  34. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/server.py +0 -0
  35. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_ads_mcp/core/utils.py +0 -0
  36. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/meta_auth_test.sh +0 -0
  37. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/requirements.txt +0 -0
  38. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/setup.py +0 -0
  39. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/smithery.yaml +0 -0
  40. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/test_meta_ads_auth.py +0 -0
  41. {meta_ads_mcp-0.3.3 → meta_ads_mcp-0.3.6}/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.3
3
+ Version: 0.3.6
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
@@ -181,38 +177,94 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
181
177
  - `adset_id`: Meta Ads ad set ID
182
178
  - Returns: Detailed information about the specified ad set
183
179
 
184
- 9. `mcp_meta_ads_get_ads`
185
- - 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
186
182
  - Inputs:
187
- - `access_token` (optional): Meta API access token (will use cached token if not provided)
188
183
  - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
189
- - `limit`: Maximum number of ads to return (default: 10)
190
- - `campaign_id`: Optional campaign ID to filter by
191
- - `adset_id`: Optional ad set ID to filter by
192
- - Returns: List of ads matching the criteria
193
-
194
- 10. `mcp_meta_ads_get_ad_details`
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`
195
222
  - Get detailed information about a specific ad
196
223
  - Inputs:
197
224
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
198
225
  - `ad_id`: Meta Ads ad ID
199
226
  - Returns: Detailed information about the specified ad
200
227
 
201
- 11. `mcp_meta_ads_get_ad_creatives`
228
+ 13. `mcp_meta_ads_get_ad_creatives`
202
229
  - Get creative details for a specific ad
203
230
  - Inputs:
204
231
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
205
232
  - `ad_id`: Meta Ads ad ID
206
233
  - Returns: Creative details including text, images, and URLs
207
234
 
208
- 12. `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`
209
261
  - Get, download, and visualize a Meta ad image in one step
210
262
  - Inputs:
211
263
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
212
264
  - `ad_id`: Meta Ads ad ID
213
265
  - Returns: The ad image ready for direct visual analysis
214
266
 
215
- 13. `mcp_meta_ads_update_ad`
267
+ 17. `mcp_meta_ads_update_ad`
216
268
  - Update an ad with new settings
217
269
  - Inputs:
218
270
  - `ad_id`: Meta Ads ad ID
@@ -221,7 +273,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
221
273
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
222
274
  - Returns: Confirmation with updated ad details and a confirmation link
223
275
 
224
- 14. `mcp_meta_ads_update_adset`
276
+ 18. `mcp_meta_ads_update_adset`
225
277
  - Update an ad set with new settings including frequency caps
226
278
  - Inputs:
227
279
  - `adset_id`: Meta Ads ad set ID
@@ -233,7 +285,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
233
285
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
234
286
  - Returns: Confirmation with updated ad set details and a confirmation link
235
287
 
236
- 15. `mcp_meta_ads_get_insights`
288
+ 19. `mcp_meta_ads_get_insights`
237
289
  - Get performance insights for a campaign, ad set, ad or account
238
290
  - Inputs:
239
291
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -243,7 +295,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
243
295
  - `level`: Level of aggregation (ad, adset, campaign, account)
244
296
  - Returns: Performance metrics for the specified object
245
297
 
246
- 16. `mcp_meta_ads_debug_image_download`
298
+ 20. `mcp_meta_ads_debug_image_download`
247
299
  - Debug image download issues and report detailed diagnostics
248
300
  - Inputs:
249
301
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -251,12 +303,23 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
251
303
  - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
252
304
  - Returns: Diagnostic information about image download attempts
253
305
 
254
- 17. `mcp_meta_ads_get_login_link`
306
+ 21. `mcp_meta_ads_get_login_link`
255
307
  - Get a clickable login link for Meta Ads authentication
256
308
  - Inputs:
257
309
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
258
310
  - Returns: A clickable resource link for Meta authentication
259
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
+
260
323
  ## Authentication
261
324
 
262
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
@@ -158,38 +154,94 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
158
154
  - `adset_id`: Meta Ads ad set ID
159
155
  - Returns: Detailed information about the specified ad set
160
156
 
161
- 9. `mcp_meta_ads_get_ads`
162
- - 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
163
159
  - Inputs:
164
- - `access_token` (optional): Meta API access token (will use cached token if not provided)
165
160
  - `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
166
- - `limit`: Maximum number of ads to return (default: 10)
167
- - `campaign_id`: Optional campaign ID to filter by
168
- - `adset_id`: Optional ad set ID to filter by
169
- - Returns: List of ads matching the criteria
170
-
171
- 10. `mcp_meta_ads_get_ad_details`
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`
172
199
  - Get detailed information about a specific ad
173
200
  - Inputs:
174
201
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
175
202
  - `ad_id`: Meta Ads ad ID
176
203
  - Returns: Detailed information about the specified ad
177
204
 
178
- 11. `mcp_meta_ads_get_ad_creatives`
205
+ 13. `mcp_meta_ads_get_ad_creatives`
179
206
  - Get creative details for a specific ad
180
207
  - Inputs:
181
208
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
182
209
  - `ad_id`: Meta Ads ad ID
183
210
  - Returns: Creative details including text, images, and URLs
184
211
 
185
- 12. `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`
186
238
  - Get, download, and visualize a Meta ad image in one step
187
239
  - Inputs:
188
240
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
189
241
  - `ad_id`: Meta Ads ad ID
190
242
  - Returns: The ad image ready for direct visual analysis
191
243
 
192
- 13. `mcp_meta_ads_update_ad`
244
+ 17. `mcp_meta_ads_update_ad`
193
245
  - Update an ad with new settings
194
246
  - Inputs:
195
247
  - `ad_id`: Meta Ads ad ID
@@ -198,7 +250,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
198
250
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
199
251
  - Returns: Confirmation with updated ad details and a confirmation link
200
252
 
201
- 14. `mcp_meta_ads_update_adset`
253
+ 18. `mcp_meta_ads_update_adset`
202
254
  - Update an ad set with new settings including frequency caps
203
255
  - Inputs:
204
256
  - `adset_id`: Meta Ads ad set ID
@@ -210,7 +262,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
210
262
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
211
263
  - Returns: Confirmation with updated ad set details and a confirmation link
212
264
 
213
- 15. `mcp_meta_ads_get_insights`
265
+ 19. `mcp_meta_ads_get_insights`
214
266
  - Get performance insights for a campaign, ad set, ad or account
215
267
  - Inputs:
216
268
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -220,7 +272,7 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
220
272
  - `level`: Level of aggregation (ad, adset, campaign, account)
221
273
  - Returns: Performance metrics for the specified object
222
274
 
223
- 16. `mcp_meta_ads_debug_image_download`
275
+ 20. `mcp_meta_ads_debug_image_download`
224
276
  - Debug image download issues and report detailed diagnostics
225
277
  - Inputs:
226
278
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
@@ -228,12 +280,23 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
228
280
  - `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
229
281
  - Returns: Diagnostic information about image download attempts
230
282
 
231
- 17. `mcp_meta_ads_get_login_link`
283
+ 21. `mcp_meta_ads_get_login_link`
232
284
  - Get a clickable login link for Meta Ads authentication
233
285
  - Inputs:
234
286
  - `access_token` (optional): Meta API access token (will use cached token if not provided)
235
287
  - Returns: A clickable resource link for Meta authentication
236
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
+
237
300
  ## Authentication
238
301
 
239
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.3"
10
+ __version__ = "0.3.6"
11
11
 
12
12
  __all__ = [
13
13
  'get_ad_accounts',
@@ -841,7 +841,7 @@ async def create_campaign(
841
841
  access_token: Meta API access token (optional - will use cached token if not provided)
842
842
  account_id: Meta Ads account ID (format: act_XXXXXXXXX)
843
843
  name: Campaign name
844
- objective: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)
844
+ objective: Campaign objective. enum{BRAND_AWARENESS, LEAD_GENERATION, LINK_CLICKS, CONVERSIONS, OUTCOME_TRAFFIC, etc.}.
845
845
  status: Initial campaign status (default: PAUSED)
846
846
  special_ad_categories: List of special ad categories if applicable
847
847
  daily_budget: Daily budget in account currency (in cents)
@@ -10,6 +10,7 @@ from .authentication import get_login_link
10
10
  from .server import login_cli, main
11
11
  from .auth import login
12
12
  from .ads_library import search_ads_archive
13
+ from .budget_schedules import create_budget_schedule
13
14
 
14
15
  __all__ = [
15
16
  'mcp_server',
@@ -33,4 +34,5 @@ __all__ = [
33
34
  'login',
34
35
  'main',
35
36
  'search_ads_archive',
37
+ 'create_budget_schedule',
36
38
  ]
@@ -0,0 +1,71 @@
1
+ """Budget Schedule-related functionality for Meta Ads API."""
2
+
3
+ import json
4
+ from typing import Optional, Dict, Any
5
+
6
+ from .api import meta_api_tool, make_api_request
7
+ from .server import mcp_server
8
+ # Assuming no other specific dependencies from adsets.py are needed for this single function.
9
+ # If other utilities from adsets.py (like get_ad_accounts) were needed, they'd be imported here.
10
+
11
+ @mcp_server.tool()
12
+ @meta_api_tool
13
+ async def create_budget_schedule(
14
+ campaign_id: str,
15
+ budget_value: int,
16
+ budget_value_type: str,
17
+ time_start: int,
18
+ time_end: int,
19
+ access_token: str = None
20
+ ) -> str:
21
+ """
22
+ Create a budget schedule for a Meta Ads campaign.
23
+
24
+ Allows scheduling budget increases based on anticipated high-demand periods.
25
+ The times should be provided as Unix timestamps.
26
+
27
+ Args:
28
+ campaign_id: Meta Ads campaign ID.
29
+ budget_value: Amount of budget increase. Interpreted based on budget_value_type.
30
+ budget_value_type: Type of budget value - "ABSOLUTE" or "MULTIPLIER".
31
+ time_start: Unix timestamp for when the high demand period should start.
32
+ time_end: Unix timestamp for when the high demand period should end.
33
+ access_token: Meta API access token (optional - will use cached token if not provided).
34
+
35
+ Returns:
36
+ A JSON string containing the ID of the created budget schedule or an error message.
37
+ """
38
+ if not campaign_id:
39
+ return json.dumps({"error": "Campaign ID is required"}, indent=2)
40
+ if budget_value is None: # Check for None explicitly
41
+ return json.dumps({"error": "Budget value is required"}, indent=2)
42
+ if not budget_value_type:
43
+ return json.dumps({"error": "Budget value type is required"}, indent=2)
44
+ if budget_value_type not in ["ABSOLUTE", "MULTIPLIER"]:
45
+ return json.dumps({"error": "Invalid budget_value_type. Must be ABSOLUTE or MULTIPLIER"}, indent=2)
46
+ if time_start is None: # Check for None explicitly to allow 0
47
+ return json.dumps({"error": "Time start is required"}, indent=2)
48
+ if time_end is None: # Check for None explicitly to allow 0
49
+ return json.dumps({"error": "Time end is required"}, indent=2)
50
+
51
+ endpoint = f"{campaign_id}/budget_schedules"
52
+
53
+ params = {
54
+ "budget_value": budget_value,
55
+ "budget_value_type": budget_value_type,
56
+ "time_start": time_start,
57
+ "time_end": time_end,
58
+ }
59
+
60
+ try:
61
+ data = await make_api_request(endpoint, access_token, params, method="POST")
62
+ return json.dumps(data, indent=2)
63
+ except Exception as e:
64
+ error_msg = str(e)
65
+ # Include details about the error and the parameters sent for easier debugging
66
+ return json.dumps({
67
+ "error": "Failed to create budget schedule",
68
+ "details": error_msg,
69
+ "campaign_id": campaign_id,
70
+ "params_sent": params
71
+ }, indent=2)
@@ -104,7 +104,7 @@ async def create_campaign(
104
104
  access_token: Meta API access token (optional - will use cached token if not provided)
105
105
  account_id: Meta Ads account ID (format: act_XXXXXXXXX)
106
106
  name: Campaign name
107
- objective: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)
107
+ objective: Campaign objective. Validates ad objectives. enum{BRAND_AWARENESS, LEAD_GENERATION, LINK_CLICKS, CONVERSIONS, OUTCOME_TRAFFIC, etc.}.
108
108
  status: Initial campaign status (default: PAUSED)
109
109
  special_ad_categories: List of special ad categories if applicable
110
110
  daily_budget: Daily budget in account currency (in cents) as a string
@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "meta-ads-mcp"
7
- version = "0.3.3"
7
+ version = "0.3.6"
8
8
  description = "Model Calling Protocol (MCP) plugin for interacting with Meta Ads API"
9
9
  readme = "README.md"
10
- requires-python = ">=3.11"
10
+ requires-python = ">=3.9.6"
11
11
  authors = [
12
12
  {name = "Yves Junqueira", email = "yves.junqueira@gmail.com"},
13
13
  ]
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes