meta-ads-mcp 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl
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.
- meta_ads_mcp/__init__.py +9 -3
- meta_ads_mcp/{meta_ads_generated.py → api.py} +39 -2
- meta_ads_mcp-0.2.1.dist-info/METADATA +329 -0
- meta_ads_mcp-0.2.1.dist-info/RECORD +6 -0
- meta_ads_mcp-0.2.1.dist-info/entry_points.txt +2 -0
- meta_ads_mcp-0.1.0.dist-info/METADATA +0 -250
- meta_ads_mcp-0.1.0.dist-info/RECORD +0 -6
- meta_ads_mcp-0.1.0.dist-info/entry_points.txt +0 -2
- {meta_ads_mcp-0.1.0.dist-info → meta_ads_mcp-0.2.1.dist-info}/WHEEL +0 -0
meta_ads_mcp/__init__.py
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
"""Meta Ads MCP - Model Calling Protocol plugin for Meta Ads API."""
|
|
2
2
|
|
|
3
|
-
__version__ = "0.1
|
|
3
|
+
__version__ = "0.2.1"
|
|
4
4
|
|
|
5
5
|
# Import key functions to make them available at package level
|
|
6
|
-
from .
|
|
6
|
+
from .api import (
|
|
7
7
|
get_ad_accounts,
|
|
8
8
|
get_account_info,
|
|
9
9
|
get_campaigns,
|
|
@@ -18,4 +18,10 @@ from .meta_ads_generated import (
|
|
|
18
18
|
get_insights,
|
|
19
19
|
get_login_link,
|
|
20
20
|
login_cli,
|
|
21
|
-
|
|
21
|
+
main, # Import main function for entry point
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
# Define a main function to be used as a package entry point
|
|
25
|
+
def entrypoint():
|
|
26
|
+
"""Main entry point for the package when invoked with uvx."""
|
|
27
|
+
return main()
|
|
@@ -298,6 +298,9 @@ class AuthManager:
|
|
|
298
298
|
except Exception as e:
|
|
299
299
|
print(f"Error removing cached token: {e}")
|
|
300
300
|
|
|
301
|
+
def clear_token(self) -> None:
|
|
302
|
+
"""Clear the current token and remove from cache"""
|
|
303
|
+
self.invalidate_token()
|
|
301
304
|
|
|
302
305
|
# Initialize auth manager
|
|
303
306
|
auth_manager = AuthManager(META_APP_ID)
|
|
@@ -1820,7 +1823,35 @@ def start_callback_server():
|
|
|
1820
1823
|
return start_callback_server() # Recursive call with a new port
|
|
1821
1824
|
raise e
|
|
1822
1825
|
|
|
1823
|
-
|
|
1826
|
+
def login_cli():
|
|
1827
|
+
"""
|
|
1828
|
+
Command line entry point for just the login function.
|
|
1829
|
+
"""
|
|
1830
|
+
# Set up command line arguments
|
|
1831
|
+
parser = argparse.ArgumentParser(description="Meta Ads Login Utility")
|
|
1832
|
+
parser.add_argument("--app-id", type=str, help="Meta App ID (Client ID) for authentication")
|
|
1833
|
+
parser.add_argument("--force-login", action="store_true", help="Force a new login even if a token exists")
|
|
1834
|
+
|
|
1835
|
+
args = parser.parse_args()
|
|
1836
|
+
|
|
1837
|
+
# Update app ID if provided
|
|
1838
|
+
if args.app_id:
|
|
1839
|
+
auth_manager.app_id = args.app_id
|
|
1840
|
+
|
|
1841
|
+
if args.force_login:
|
|
1842
|
+
# Clear existing token
|
|
1843
|
+
auth_manager.clear_token()
|
|
1844
|
+
|
|
1845
|
+
# Perform login
|
|
1846
|
+
login()
|
|
1847
|
+
|
|
1848
|
+
return 0
|
|
1849
|
+
|
|
1850
|
+
def main():
|
|
1851
|
+
"""
|
|
1852
|
+
Main entry point for the Meta Ads MCP server.
|
|
1853
|
+
This function handles command line arguments and runs the server.
|
|
1854
|
+
"""
|
|
1824
1855
|
# Set up command line arguments
|
|
1825
1856
|
parser = argparse.ArgumentParser(description="Meta Ads MCP Server")
|
|
1826
1857
|
parser.add_argument("--login", action="store_true", help="Authenticate with Meta and store the token")
|
|
@@ -1837,4 +1868,10 @@ if __name__ == "__main__":
|
|
|
1837
1868
|
login()
|
|
1838
1869
|
else:
|
|
1839
1870
|
# Initialize and run the server
|
|
1840
|
-
mcp_server.run(transport='stdio')
|
|
1871
|
+
mcp_server.run(transport='stdio')
|
|
1872
|
+
|
|
1873
|
+
return 0
|
|
1874
|
+
|
|
1875
|
+
# Modify the if __name__ block to use the main function
|
|
1876
|
+
if __name__ == "__main__":
|
|
1877
|
+
main()
|
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: meta-ads-mcp
|
|
3
|
+
Version: 0.2.1
|
|
4
|
+
Summary: Model Calling Protocol (MCP) plugin for interacting with Meta Ads API
|
|
5
|
+
Project-URL: Homepage, https://github.com/nictuku/meta-ads-mcp
|
|
6
|
+
Project-URL: Bug Tracker, https://github.com/nictuku/meta-ads-mcp/issues
|
|
7
|
+
Author-email: Your Name <your.email@example.com>
|
|
8
|
+
License: MIT
|
|
9
|
+
Keywords: ads,api,claude,facebook,mcp,meta
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Requires-Python: >=3.11
|
|
14
|
+
Requires-Dist: httpx>=0.26.0
|
|
15
|
+
Requires-Dist: mcp[cli]>=1.6.0
|
|
16
|
+
Requires-Dist: pathlib>=1.0.1
|
|
17
|
+
Requires-Dist: pillow>=10.0.0
|
|
18
|
+
Requires-Dist: python-dotenv>=1.1.0
|
|
19
|
+
Requires-Dist: requests>=2.32.3
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
# Meta Ads MCP
|
|
23
|
+
|
|
24
|
+
A [Model Calling Protocol (MCP)](https://github.com/anthropics/anthropic-tools) plugin for interacting with Meta Ads API.
|
|
25
|
+
|
|
26
|
+
## Features
|
|
27
|
+
|
|
28
|
+
- Seamless authentication with Meta's Graph API for desktop applications
|
|
29
|
+
- Automatic token caching across sessions
|
|
30
|
+
- Cross-platform support (Windows, macOS, Linux)
|
|
31
|
+
- Access to ad accounts, campaigns, ad sets, and ads
|
|
32
|
+
- Image download and analysis capabilities
|
|
33
|
+
- Performance insights
|
|
34
|
+
|
|
35
|
+
## Installation
|
|
36
|
+
|
|
37
|
+
### Using uv (recommended)
|
|
38
|
+
|
|
39
|
+
When using uv no specific installation is needed. We can use uvx to directly run meta-ads-mcp:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
uvx meta-ads-mcp
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
If you want to install the package:
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
uv pip install meta-ads-mcp
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
For development (if you've cloned the repository):
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
# From the repository root
|
|
55
|
+
uv pip install -e .
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Using pip
|
|
59
|
+
|
|
60
|
+
Alternatively, you can install meta-ads-mcp via pip:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
pip install meta-ads-mcp
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
After installation, you can run it as:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
python -m meta_ads_mcp
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
## Configuration
|
|
73
|
+
|
|
74
|
+
### Usage with Claude in Cursor
|
|
75
|
+
|
|
76
|
+
Add this to your `claude_desktop_config.json` to integrate with Claude in Cursor:
|
|
77
|
+
|
|
78
|
+
```json
|
|
79
|
+
"mcpServers": {
|
|
80
|
+
"meta-ads": {
|
|
81
|
+
"command": "uvx",
|
|
82
|
+
"args": ["meta-ads-mcp"]
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
### Available MCP Tools
|
|
88
|
+
|
|
89
|
+
1. `mcp_meta_ads_get_ad_accounts`
|
|
90
|
+
- Get ad accounts accessible by a user
|
|
91
|
+
- Inputs:
|
|
92
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
93
|
+
- `user_id`: Meta user ID or "me" for the current user
|
|
94
|
+
- `limit`: Maximum number of accounts to return (default: 10)
|
|
95
|
+
- Returns: List of accessible ad accounts with their details
|
|
96
|
+
|
|
97
|
+
2. `mcp_meta_ads_get_account_info`
|
|
98
|
+
- Get detailed information about a specific ad account
|
|
99
|
+
- Inputs:
|
|
100
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
101
|
+
- `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
|
|
102
|
+
- Returns: Detailed information about the specified account
|
|
103
|
+
|
|
104
|
+
3. `mcp_meta_ads_get_campaigns`
|
|
105
|
+
- Get campaigns for a Meta Ads account with optional filtering
|
|
106
|
+
- Inputs:
|
|
107
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
108
|
+
- `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
|
|
109
|
+
- `limit`: Maximum number of campaigns to return (default: 10)
|
|
110
|
+
- `status_filter`: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
|
|
111
|
+
- Returns: List of campaigns matching the criteria
|
|
112
|
+
|
|
113
|
+
4. `mcp_meta_ads_get_campaign_details`
|
|
114
|
+
- Get detailed information about a specific campaign
|
|
115
|
+
- Inputs:
|
|
116
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
117
|
+
- `campaign_id`: Meta Ads campaign ID
|
|
118
|
+
- Returns: Detailed information about the specified campaign
|
|
119
|
+
|
|
120
|
+
5. `mcp_meta_ads_create_campaign`
|
|
121
|
+
- Create a new campaign in a Meta Ads account
|
|
122
|
+
- Inputs:
|
|
123
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
124
|
+
- `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
|
|
125
|
+
- `name`: Campaign name
|
|
126
|
+
- `objective`: Campaign objective (AWARENESS, TRAFFIC, ENGAGEMENT, etc.)
|
|
127
|
+
- `status`: Initial campaign status (default: PAUSED)
|
|
128
|
+
- `special_ad_categories`: List of special ad categories if applicable
|
|
129
|
+
- `daily_budget`: Daily budget in account currency (in cents)
|
|
130
|
+
- `lifetime_budget`: Lifetime budget in account currency (in cents)
|
|
131
|
+
- Returns: Confirmation with new campaign details
|
|
132
|
+
|
|
133
|
+
6. `mcp_meta_ads_get_adsets`
|
|
134
|
+
- Get ad sets for a Meta Ads account with optional filtering by campaign
|
|
135
|
+
- Inputs:
|
|
136
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
137
|
+
- `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
|
|
138
|
+
- `limit`: Maximum number of ad sets to return (default: 10)
|
|
139
|
+
- `campaign_id`: Optional campaign ID to filter by
|
|
140
|
+
- Returns: List of ad sets matching the criteria
|
|
141
|
+
|
|
142
|
+
7. `mcp_meta_ads_get_adset_details`
|
|
143
|
+
- Get detailed information about a specific ad set
|
|
144
|
+
- Inputs:
|
|
145
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
146
|
+
- `adset_id`: Meta Ads ad set ID
|
|
147
|
+
- Returns: Detailed information about the specified ad set
|
|
148
|
+
|
|
149
|
+
8. `mcp_meta_ads_get_ads`
|
|
150
|
+
- Get ads for a Meta Ads account with optional filtering
|
|
151
|
+
- Inputs:
|
|
152
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
153
|
+
- `account_id`: Meta Ads account ID (format: act_XXXXXXXXX)
|
|
154
|
+
- `limit`: Maximum number of ads to return (default: 10)
|
|
155
|
+
- `campaign_id`: Optional campaign ID to filter by
|
|
156
|
+
- `adset_id`: Optional ad set ID to filter by
|
|
157
|
+
- Returns: List of ads matching the criteria
|
|
158
|
+
|
|
159
|
+
9. `mcp_meta_ads_get_ad_details`
|
|
160
|
+
- Get detailed information about a specific ad
|
|
161
|
+
- Inputs:
|
|
162
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
163
|
+
- `ad_id`: Meta Ads ad ID
|
|
164
|
+
- Returns: Detailed information about the specified ad
|
|
165
|
+
|
|
166
|
+
10. `mcp_meta_ads_get_ad_creatives`
|
|
167
|
+
- Get creative details for a specific ad
|
|
168
|
+
- Inputs:
|
|
169
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
170
|
+
- `ad_id`: Meta Ads ad ID
|
|
171
|
+
- Returns: Creative details including text, images, and URLs
|
|
172
|
+
|
|
173
|
+
11. `mcp_meta_ads_get_ad_image`
|
|
174
|
+
- Get, download, and visualize a Meta ad image in one step
|
|
175
|
+
- Inputs:
|
|
176
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
177
|
+
- `ad_id`: Meta Ads ad ID
|
|
178
|
+
- Returns: The ad image ready for direct visual analysis
|
|
179
|
+
|
|
180
|
+
12. `mcp_meta_ads_get_insights`
|
|
181
|
+
- Get performance insights for a campaign, ad set, ad or account
|
|
182
|
+
- Inputs:
|
|
183
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
184
|
+
- `object_id`: ID of the campaign, ad set, ad or account
|
|
185
|
+
- `time_range`: Time range for insights (default: maximum)
|
|
186
|
+
- `breakdown`: Optional breakdown dimension (e.g., age, gender, country)
|
|
187
|
+
- `level`: Level of aggregation (ad, adset, campaign, account)
|
|
188
|
+
- Returns: Performance metrics for the specified object
|
|
189
|
+
|
|
190
|
+
13. `mcp_meta_ads_debug_image_download`
|
|
191
|
+
- Debug image download issues and report detailed diagnostics
|
|
192
|
+
- Inputs:
|
|
193
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
194
|
+
- `url`: Direct image URL to test (optional)
|
|
195
|
+
- `ad_id`: Meta Ads ad ID (optional, used if url is not provided)
|
|
196
|
+
- Returns: Diagnostic information about image download attempts
|
|
197
|
+
|
|
198
|
+
14. `mcp_meta_ads_save_ad_image_via_api`
|
|
199
|
+
- Try to save an ad image by using the Marketing API's attachment endpoints
|
|
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: Results of attempts to save the ad image
|
|
204
|
+
|
|
205
|
+
15. `mcp_meta_ads_get_login_link`
|
|
206
|
+
- Get a clickable login link for Meta Ads authentication
|
|
207
|
+
- Inputs:
|
|
208
|
+
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
209
|
+
- Returns: A clickable resource link for Meta authentication
|
|
210
|
+
|
|
211
|
+
## Create a Meta Developer App
|
|
212
|
+
|
|
213
|
+
Before using the MCP server, you'll need to set up a Meta Developer App:
|
|
214
|
+
|
|
215
|
+
1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
|
|
216
|
+
2. Choose the "Consumer" app type
|
|
217
|
+
3. In your app settings, add the "Marketing API" product
|
|
218
|
+
4. Configure your app's OAuth redirect URI to include `http://localhost:8888/callback`
|
|
219
|
+
5. Note your App ID (Client ID) for use with the MCP
|
|
220
|
+
|
|
221
|
+
## Authentication
|
|
222
|
+
|
|
223
|
+
The Meta Ads MCP uses the OAuth 2.0 flow designed for desktop apps. When authenticating, it will:
|
|
224
|
+
|
|
225
|
+
1. Start a local callback server on your machine
|
|
226
|
+
2. Open a browser window to authenticate with Meta
|
|
227
|
+
3. Ask you to authorize the app
|
|
228
|
+
4. Redirect back to the local server to extract and store the token securely
|
|
229
|
+
|
|
230
|
+
### Authentication Methods
|
|
231
|
+
|
|
232
|
+
There are two ways to authenticate with the Meta Ads API:
|
|
233
|
+
|
|
234
|
+
1. **LLM/MCP Interface Authentication** (Recommended)
|
|
235
|
+
|
|
236
|
+
When using the Meta Ads MCP through an LLM interface (like Claude), simply use any Meta Ads function. If you're not authenticated, the system will automatically provide a clickable Markdown link to complete the authentication flow.
|
|
237
|
+
|
|
238
|
+
```
|
|
239
|
+
[Click here to authenticate with Meta Ads API](https://www.facebook.com/dialog/oauth?...)
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
Just click the link, complete the authorization in your browser, and the token will be automatically captured and stored.
|
|
243
|
+
|
|
244
|
+
2. **Command Line Authentication**
|
|
245
|
+
|
|
246
|
+
You can authenticate directly from the command line:
|
|
247
|
+
|
|
248
|
+
```bash
|
|
249
|
+
uvx meta-ads-mcp --login --app-id YOUR_APP_ID
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
### Token Caching
|
|
253
|
+
|
|
254
|
+
Tokens are cached in a platform-specific secure location:
|
|
255
|
+
- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
|
|
256
|
+
- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
|
|
257
|
+
- Linux: `~/.config/meta-ads-mcp/token_cache.json`
|
|
258
|
+
|
|
259
|
+
You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
|
|
260
|
+
|
|
261
|
+
## Environment Variables
|
|
262
|
+
|
|
263
|
+
You can set the following environment variables instead of passing them as arguments:
|
|
264
|
+
|
|
265
|
+
- `META_APP_ID`: Your Meta App ID (Client ID)
|
|
266
|
+
|
|
267
|
+
## Testing
|
|
268
|
+
|
|
269
|
+
### CLI Testing
|
|
270
|
+
|
|
271
|
+
Run the test script to verify authentication and basic functionality:
|
|
272
|
+
|
|
273
|
+
```bash
|
|
274
|
+
python test_meta_ads_auth.py --app-id YOUR_APP_ID
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Use the `--force-login` flag to force a new authentication even if a cached token exists:
|
|
278
|
+
|
|
279
|
+
```bash
|
|
280
|
+
python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
### LLM Interface Testing
|
|
284
|
+
|
|
285
|
+
When using the Meta Ads MCP with an LLM interface (like Claude):
|
|
286
|
+
|
|
287
|
+
1. Test authentication by calling the `mcp_meta_ads_get_login_link` tool
|
|
288
|
+
2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
|
|
289
|
+
3. Check specific account details with `mcp_meta_ads_get_account_info`
|
|
290
|
+
|
|
291
|
+
These functions will automatically handle authentication if needed and provide a clickable login link.
|
|
292
|
+
|
|
293
|
+
## Troubleshooting
|
|
294
|
+
|
|
295
|
+
### Authentication Issues
|
|
296
|
+
|
|
297
|
+
If you encounter authentication issues:
|
|
298
|
+
|
|
299
|
+
1. When using the LLM interface:
|
|
300
|
+
- Use the `mcp_meta_ads_get_login_link` tool to generate a fresh authentication link
|
|
301
|
+
- Ensure you click the link and complete the authorization flow in your browser
|
|
302
|
+
- Check that the callback server is running properly (the tool will report this)
|
|
303
|
+
|
|
304
|
+
2. When using the command line:
|
|
305
|
+
- Run with `--force-login` to get a fresh token: `uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login`
|
|
306
|
+
- Make sure the terminal has permissions to open a browser window
|
|
307
|
+
|
|
308
|
+
3. General authentication troubleshooting:
|
|
309
|
+
- Check that your app is properly configured in the Meta Developers portal
|
|
310
|
+
- Ensure your app has the necessary permissions (ads_management, ads_read, business_management)
|
|
311
|
+
- Verify the app's redirect URI includes `http://localhost:8888/callback`
|
|
312
|
+
- Try clearing the token cache (located in platform-specific directories listed in the Token Caching section)
|
|
313
|
+
|
|
314
|
+
### API Errors
|
|
315
|
+
|
|
316
|
+
If you receive errors from the Meta API:
|
|
317
|
+
|
|
318
|
+
1. Verify your app has the Marketing API product added
|
|
319
|
+
2. Ensure the user has appropriate permissions on the ad accounts
|
|
320
|
+
3. Check if there are rate limits or other restrictions on your app
|
|
321
|
+
|
|
322
|
+
## Versioning
|
|
323
|
+
|
|
324
|
+
You can check the current version of the package:
|
|
325
|
+
|
|
326
|
+
```python
|
|
327
|
+
import meta_ads_mcp
|
|
328
|
+
print(meta_ads_mcp.__version__)
|
|
329
|
+
```
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
meta_ads_mcp/__init__.py,sha256=a8UpoSlu32NXZZyxCAXaXZ_o8Uo8UnrzPkqF1fSA4JA,665
|
|
2
|
+
meta_ads_mcp/api.py,sha256=sahhuPeYSJN2uYjyDDXSd68MXD04gzcrTLn7wTs1A_0,74055
|
|
3
|
+
meta_ads_mcp-0.2.1.dist-info/METADATA,sha256=qKyZfRYiesCRlaHg854-jRownsgfBrChv1pnmV1OYPg,12045
|
|
4
|
+
meta_ads_mcp-0.2.1.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
5
|
+
meta_ads_mcp-0.2.1.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
|
|
6
|
+
meta_ads_mcp-0.2.1.dist-info/RECORD,,
|
|
@@ -1,250 +0,0 @@
|
|
|
1
|
-
Metadata-Version: 2.4
|
|
2
|
-
Name: meta-ads-mcp
|
|
3
|
-
Version: 0.1.0
|
|
4
|
-
Summary: Model Calling Protocol (MCP) plugin for interacting with Meta Ads API
|
|
5
|
-
Project-URL: Homepage, https://github.com/nictuku/meta-ads-mcp
|
|
6
|
-
Project-URL: Bug Tracker, https://github.com/nictuku/meta-ads-mcp/issues
|
|
7
|
-
Author-email: Your Name <your.email@example.com>
|
|
8
|
-
License: MIT
|
|
9
|
-
Keywords: ads,api,claude,facebook,mcp,meta
|
|
10
|
-
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
-
Classifier: Operating System :: OS Independent
|
|
12
|
-
Classifier: Programming Language :: Python :: 3
|
|
13
|
-
Requires-Python: >=3.11
|
|
14
|
-
Requires-Dist: httpx>=0.26.0
|
|
15
|
-
Requires-Dist: mcp[cli]>=1.6.0
|
|
16
|
-
Requires-Dist: pathlib>=1.0.1
|
|
17
|
-
Requires-Dist: pillow>=10.0.0
|
|
18
|
-
Requires-Dist: python-dotenv>=1.1.0
|
|
19
|
-
Requires-Dist: requests>=2.32.3
|
|
20
|
-
Description-Content-Type: text/markdown
|
|
21
|
-
|
|
22
|
-
# Meta Ads MCP
|
|
23
|
-
|
|
24
|
-
A [Model Calling Protocol (MCP)](https://github.com/anthropics/anthropic-tools) plugin for interacting with Meta Ads API.
|
|
25
|
-
|
|
26
|
-
## Features
|
|
27
|
-
|
|
28
|
-
- Seamless authentication with Meta's Graph API for desktop applications
|
|
29
|
-
- Automatic token caching across sessions
|
|
30
|
-
- Cross-platform support (Windows, macOS, Linux)
|
|
31
|
-
- Access to ad accounts, campaigns, ad sets, and ads
|
|
32
|
-
- Image download and analysis capabilities
|
|
33
|
-
- Performance insights
|
|
34
|
-
|
|
35
|
-
## Setup
|
|
36
|
-
|
|
37
|
-
### 1. Create a Meta Developer App
|
|
38
|
-
|
|
39
|
-
1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
|
|
40
|
-
2. Choose the "Consumer" app type
|
|
41
|
-
3. In your app settings, add the "Marketing API" product
|
|
42
|
-
4. Configure your app's OAuth redirect URI to include `http://localhost:8888/callback`
|
|
43
|
-
5. Note your App ID (Client ID) for use with the MCP
|
|
44
|
-
|
|
45
|
-
### 2. Install the Package
|
|
46
|
-
|
|
47
|
-
#### Using uv (Recommended)
|
|
48
|
-
|
|
49
|
-
Install directly from GitHub:
|
|
50
|
-
|
|
51
|
-
```bash
|
|
52
|
-
uv pip install git+https://github.com/nictuku/meta-ads-mcp.git
|
|
53
|
-
```
|
|
54
|
-
|
|
55
|
-
Or if you've cloned the repository:
|
|
56
|
-
|
|
57
|
-
```bash
|
|
58
|
-
# From the repository root
|
|
59
|
-
uv pip install -e .
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
#### Using pip
|
|
63
|
-
|
|
64
|
-
```bash
|
|
65
|
-
pip install git+https://github.com/nictuku/meta-ads-mcp.git
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
### 3. Install Dependencies (If installing from source)
|
|
69
|
-
|
|
70
|
-
```bash
|
|
71
|
-
uv pip install -r requirements.txt
|
|
72
|
-
```
|
|
73
|
-
|
|
74
|
-
Or:
|
|
75
|
-
|
|
76
|
-
```bash
|
|
77
|
-
pip install -r requirements.txt
|
|
78
|
-
```
|
|
79
|
-
|
|
80
|
-
## Authentication
|
|
81
|
-
|
|
82
|
-
The Meta Ads MCP uses the OAuth 2.0 flow designed for desktop apps. When authenticating, it will:
|
|
83
|
-
|
|
84
|
-
1. Start a local callback server on your machine
|
|
85
|
-
2. Open a browser window to authenticate with Meta
|
|
86
|
-
3. Ask you to authorize the app
|
|
87
|
-
4. Redirect back to the local server to extract and store the token securely
|
|
88
|
-
|
|
89
|
-
### Authentication Methods
|
|
90
|
-
|
|
91
|
-
There are two ways to authenticate with the Meta Ads API:
|
|
92
|
-
|
|
93
|
-
1. **LLM/MCP Interface Authentication** (Recommended)
|
|
94
|
-
|
|
95
|
-
When using the Meta Ads MCP through an LLM interface (like Claude), simply use any Meta Ads function. If you're not authenticated, the system will automatically provide a clickable Markdown link to complete the authentication flow.
|
|
96
|
-
|
|
97
|
-
```
|
|
98
|
-
[Click here to authenticate with Meta Ads API](https://www.facebook.com/dialog/oauth?...)
|
|
99
|
-
```
|
|
100
|
-
|
|
101
|
-
Just click the link, complete the authorization in your browser, and the token will be automatically captured and stored.
|
|
102
|
-
|
|
103
|
-
2. **Command Line Authentication**
|
|
104
|
-
|
|
105
|
-
You can also initiate authentication directly from the command line:
|
|
106
|
-
|
|
107
|
-
```bash
|
|
108
|
-
python meta_ads_generated.py --login --app-id YOUR_APP_ID
|
|
109
|
-
```
|
|
110
|
-
|
|
111
|
-
Or use the convenience scripts:
|
|
112
|
-
|
|
113
|
-
```bash
|
|
114
|
-
# On macOS/Linux
|
|
115
|
-
./login.sh YOUR_APP_ID
|
|
116
|
-
|
|
117
|
-
# On Windows
|
|
118
|
-
login.bat YOUR_APP_ID
|
|
119
|
-
```
|
|
120
|
-
|
|
121
|
-
### Token Caching
|
|
122
|
-
|
|
123
|
-
Tokens are cached in a platform-specific secure location:
|
|
124
|
-
- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
|
|
125
|
-
- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
|
|
126
|
-
- Linux: `~/.config/meta-ads-mcp/token_cache.json`
|
|
127
|
-
|
|
128
|
-
You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
|
|
129
|
-
|
|
130
|
-
## Usage Examples
|
|
131
|
-
|
|
132
|
-
### Test Authentication
|
|
133
|
-
|
|
134
|
-
```bash
|
|
135
|
-
python test_meta_ads_auth.py --app-id YOUR_APP_ID
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
### Get Ad Accounts
|
|
139
|
-
|
|
140
|
-
```python
|
|
141
|
-
import asyncio
|
|
142
|
-
from meta_ads_mcp import get_ad_accounts
|
|
143
|
-
|
|
144
|
-
async def main():
|
|
145
|
-
# Token will be automatically retrieved from cache
|
|
146
|
-
accounts_json = await get_ad_accounts()
|
|
147
|
-
print(accounts_json)
|
|
148
|
-
|
|
149
|
-
asyncio.run(main())
|
|
150
|
-
```
|
|
151
|
-
|
|
152
|
-
### Get Campaign Details
|
|
153
|
-
|
|
154
|
-
```python
|
|
155
|
-
import asyncio
|
|
156
|
-
from meta_ads_mcp import get_campaign_details
|
|
157
|
-
|
|
158
|
-
async def main():
|
|
159
|
-
# Provide a campaign ID
|
|
160
|
-
campaign_details = await get_campaign_details(campaign_id="123456789")
|
|
161
|
-
print(campaign_details)
|
|
162
|
-
|
|
163
|
-
asyncio.run(main())
|
|
164
|
-
```
|
|
165
|
-
|
|
166
|
-
### Create a Campaign
|
|
167
|
-
|
|
168
|
-
```python
|
|
169
|
-
import asyncio
|
|
170
|
-
from meta_ads_mcp import create_campaign
|
|
171
|
-
|
|
172
|
-
async def main():
|
|
173
|
-
result = await create_campaign(
|
|
174
|
-
account_id="act_123456789",
|
|
175
|
-
name="Test Campaign via MCP",
|
|
176
|
-
objective="AWARENESS",
|
|
177
|
-
status="PAUSED",
|
|
178
|
-
daily_budget=1000 # $10.00
|
|
179
|
-
)
|
|
180
|
-
print(result)
|
|
181
|
-
|
|
182
|
-
asyncio.run(main())
|
|
183
|
-
```
|
|
184
|
-
|
|
185
|
-
## Environment Variables
|
|
186
|
-
|
|
187
|
-
You can set the following environment variables instead of passing them as arguments:
|
|
188
|
-
|
|
189
|
-
- `META_APP_ID`: Your Meta App ID (Client ID)
|
|
190
|
-
|
|
191
|
-
## Testing
|
|
192
|
-
|
|
193
|
-
### CLI Testing
|
|
194
|
-
|
|
195
|
-
Run the test script to verify authentication and basic functionality:
|
|
196
|
-
|
|
197
|
-
```bash
|
|
198
|
-
python test_meta_ads_auth.py --app-id YOUR_APP_ID
|
|
199
|
-
```
|
|
200
|
-
|
|
201
|
-
Use the `--force-login` flag to force a new authentication even if a cached token exists:
|
|
202
|
-
|
|
203
|
-
```bash
|
|
204
|
-
python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
|
|
205
|
-
```
|
|
206
|
-
|
|
207
|
-
### LLM Interface Testing
|
|
208
|
-
|
|
209
|
-
When using the Meta Ads MCP with an LLM interface (like Claude):
|
|
210
|
-
|
|
211
|
-
1. Test authentication by calling the `get_login_link` tool
|
|
212
|
-
2. Verify account access by calling `get_ad_accounts`
|
|
213
|
-
3. Check specific account details with `get_account_info`
|
|
214
|
-
|
|
215
|
-
These functions will automatically handle authentication if needed and provide a clickable login link.
|
|
216
|
-
|
|
217
|
-
## Troubleshooting
|
|
218
|
-
|
|
219
|
-
### Authentication Issues
|
|
220
|
-
|
|
221
|
-
If you encounter authentication issues:
|
|
222
|
-
|
|
223
|
-
1. When using the LLM interface:
|
|
224
|
-
- Use the `get_login_link` tool to generate a fresh authentication link
|
|
225
|
-
- Ensure you click the link and complete the authorization flow in your browser
|
|
226
|
-
- Check that the callback server is running properly (the tool will report this)
|
|
227
|
-
|
|
228
|
-
2. When using the command line:
|
|
229
|
-
- Run with `--force-login` to get a fresh token: `python meta_ads_generated.py --login --app-id YOUR_APP_ID --force-login`
|
|
230
|
-
- Make sure the terminal has permissions to open a browser window
|
|
231
|
-
|
|
232
|
-
3. General authentication troubleshooting:
|
|
233
|
-
- Check that your app is properly configured in the Meta Developers portal
|
|
234
|
-
- Ensure your app has the necessary permissions (ads_management, ads_read, business_management)
|
|
235
|
-
- Verify the app's redirect URI includes `http://localhost:8888/callback`
|
|
236
|
-
- Try clearing the token cache (located in platform-specific directories listed in the Token Caching section)
|
|
237
|
-
|
|
238
|
-
### API Errors
|
|
239
|
-
|
|
240
|
-
If you receive errors from the Meta API:
|
|
241
|
-
|
|
242
|
-
1. Verify your app has the Marketing API product added
|
|
243
|
-
2. Ensure the user has appropriate permissions on the ad accounts
|
|
244
|
-
3. Check if there are rate limits or other restrictions on your app
|
|
245
|
-
|
|
246
|
-
## Files
|
|
247
|
-
|
|
248
|
-
This repository contains the implementation for the Meta Ads Marketing API Client Protocol (MCP).
|
|
249
|
-
|
|
250
|
-
- `meta_ads_generated.py`: The main MCP implementation for Meta Ads API
|
|
@@ -1,6 +0,0 @@
|
|
|
1
|
-
meta_ads_mcp/__init__.py,sha256=wxUeUJcUa1OcuMQqDjTlMBT5QVYTWdK2Taq6yrGpLOw,466
|
|
2
|
-
meta_ads_mcp/meta_ads_generated.py,sha256=lJDU3347bQNnGmjnD30pS4uT_h7l34rvxcyKIR2CJuk,72997
|
|
3
|
-
meta_ads_mcp-0.1.0.dist-info/METADATA,sha256=IV_vJOI0DIHChre6XAm_1xXV2crCeMXXbh5hdF7B13c,7021
|
|
4
|
-
meta_ads_mcp-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
5
|
-
meta_ads_mcp-0.1.0.dist-info/entry_points.txt,sha256=LKUVEPu7YWYjULD_OQMDIRn3IPql-6ERcxoM2fxWVUQ,77
|
|
6
|
-
meta_ads_mcp-0.1.0.dist-info/RECORD,,
|
|
File without changes
|