meta-ads-mcp 0.3.5__tar.gz → 0.3.7__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.
- meta_ads_mcp-0.3.7/.github/workflows/publish.yml +39 -0
- meta_ads_mcp-0.3.7/.github/workflows/test.yml +56 -0
- meta_ads_mcp-0.3.7/CUSTOM_META_APP.md +110 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/PKG-INFO +83 -188
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/README.md +81 -186
- meta_ads_mcp-0.3.7/RELEASE.md +91 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/__init__.py +1 -1
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/api.py +6 -2
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/api.py +10 -2
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/authentication.py +1 -1
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/campaigns.py +6 -2
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/utils.py +6 -2
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/pyproject.toml +2 -2
- meta_ads_mcp-0.3.7/requirements.txt +7 -0
- meta_ads_mcp-0.3.5/brands/injurypayouts.com/120221013820800183_76c8b7fd0c627bce0d6ad833682f45e5.jpg +0 -0
- meta_ads_mcp-0.3.5/brands/injurypayouts.com/120221013841190183_cc1ff1ad28a037f397fd0e1636e8239a.jpg +0 -0
- meta_ads_mcp-0.3.5/brands/injurypayouts.com/120221013863110183_76f042047ce288bfbf9e103ffa10c50f.jpg +0 -0
- meta_ads_mcp-0.3.5/requirements.txt +0 -4
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/.gitignore +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/Dockerfile +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/LICENSE +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/META_API_NOTES.md +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/debug_meta_api_tool.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/debug_token_flow.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/future_improvements.md +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/images/meta-ads-example.png +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta-ads-mcp +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_auth.sh +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/__main__.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/__init__.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/accounts.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/ads.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/ads_library.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/adsets.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/auth.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/budget_schedules.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/callback_server.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/insights.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/pipeboard_auth.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/resources.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_ads_mcp/core/server.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/meta_auth_test.sh +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/setup.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/smithery.yaml +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/test_meta_ads_auth.py +0 -0
- {meta_ads_mcp-0.3.5 → meta_ads_mcp-0.3.7}/test_pipeboard_auth.py +0 -0
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
# Allow manual triggering for testing
|
|
7
|
+
workflow_dispatch:
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
publish:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
environment: release
|
|
13
|
+
permissions:
|
|
14
|
+
id-token: write # IMPORTANT: this permission is mandatory for trusted publishing
|
|
15
|
+
contents: read
|
|
16
|
+
|
|
17
|
+
steps:
|
|
18
|
+
- name: Check out code
|
|
19
|
+
uses: actions/checkout@v4
|
|
20
|
+
|
|
21
|
+
- name: Set up Python
|
|
22
|
+
uses: actions/setup-python@v5
|
|
23
|
+
with:
|
|
24
|
+
python-version: "3.10"
|
|
25
|
+
|
|
26
|
+
- name: Install build dependencies
|
|
27
|
+
run: |
|
|
28
|
+
python -m pip install --upgrade pip
|
|
29
|
+
pip install build
|
|
30
|
+
|
|
31
|
+
- name: Build package
|
|
32
|
+
run: python -m build
|
|
33
|
+
|
|
34
|
+
- name: Publish to PyPI
|
|
35
|
+
uses: pypa/gh-action-pypi-publish@release/v1
|
|
36
|
+
with:
|
|
37
|
+
# Using trusted publishing (no API token needed)
|
|
38
|
+
# Make sure to configure trusted publishing in PyPI project settings
|
|
39
|
+
verbose: true
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
name: Test and Build
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [ main, master ]
|
|
6
|
+
pull_request:
|
|
7
|
+
branches: [ main, master ]
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
test:
|
|
11
|
+
runs-on: ubuntu-latest
|
|
12
|
+
strategy:
|
|
13
|
+
matrix:
|
|
14
|
+
python-version: ["3.10", "3.11", "3.12"]
|
|
15
|
+
|
|
16
|
+
steps:
|
|
17
|
+
- name: Check out code
|
|
18
|
+
uses: actions/checkout@v4
|
|
19
|
+
|
|
20
|
+
- name: Set up Python ${{ matrix.python-version }}
|
|
21
|
+
uses: actions/setup-python@v5
|
|
22
|
+
with:
|
|
23
|
+
python-version: ${{ matrix.python-version }}
|
|
24
|
+
|
|
25
|
+
- name: Install dependencies
|
|
26
|
+
run: |
|
|
27
|
+
python -m pip install --upgrade pip
|
|
28
|
+
pip install build pytest
|
|
29
|
+
pip install -e .
|
|
30
|
+
|
|
31
|
+
- name: Test package build
|
|
32
|
+
run: python -m build
|
|
33
|
+
|
|
34
|
+
- name: Test package installation
|
|
35
|
+
run: |
|
|
36
|
+
pip install dist/*.whl
|
|
37
|
+
python -c "import meta_ads_mcp; print('Package imported successfully')"
|
|
38
|
+
|
|
39
|
+
validate-version:
|
|
40
|
+
runs-on: ubuntu-latest
|
|
41
|
+
if: github.event_name == 'pull_request'
|
|
42
|
+
|
|
43
|
+
steps:
|
|
44
|
+
- name: Check out code
|
|
45
|
+
uses: actions/checkout@v4
|
|
46
|
+
|
|
47
|
+
- name: Set up Python
|
|
48
|
+
uses: actions/setup-python@v5
|
|
49
|
+
with:
|
|
50
|
+
python-version: "3.10"
|
|
51
|
+
|
|
52
|
+
- name: Check version bump
|
|
53
|
+
run: |
|
|
54
|
+
# This is a simple check - you might want to make it more sophisticated
|
|
55
|
+
echo "Current version in pyproject.toml:"
|
|
56
|
+
grep "version = " pyproject.toml
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
# Using a Custom Meta Developer App
|
|
2
|
+
|
|
3
|
+
This guide explains how to use Meta Ads MCP with your own Meta Developer App. Note that this is an alternative method - we recommend using [Pipeboard authentication](README.md) for a simpler setup.
|
|
4
|
+
|
|
5
|
+
## Create a Meta Developer App
|
|
6
|
+
|
|
7
|
+
Before using direct Meta authentication, you'll need to set up a Meta Developer App:
|
|
8
|
+
|
|
9
|
+
1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
|
|
10
|
+
2. Choose the "Business" app type
|
|
11
|
+
3. In your app settings, add the "Marketing API" product
|
|
12
|
+
4. Configure your app's OAuth redirect URI to include `http://localhost:8888/callback`
|
|
13
|
+
5. Note your App ID (Client ID) for use with the MCP
|
|
14
|
+
|
|
15
|
+
## Installation & Usage
|
|
16
|
+
|
|
17
|
+
When using your own Meta app, you'll need to provide the App ID:
|
|
18
|
+
|
|
19
|
+
```bash
|
|
20
|
+
# Using uvx
|
|
21
|
+
uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID
|
|
22
|
+
|
|
23
|
+
# Using pip installation
|
|
24
|
+
python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Configuration
|
|
28
|
+
|
|
29
|
+
### Cursor or Claude Desktop Integration
|
|
30
|
+
|
|
31
|
+
Add this to your `claude_desktop_config.json` or `~/.cursor/mcp.json`:
|
|
32
|
+
|
|
33
|
+
```json
|
|
34
|
+
"mcpServers": {
|
|
35
|
+
"meta-ads": {
|
|
36
|
+
"command": "uvx",
|
|
37
|
+
"args": ["meta-ads-mcp", "--app-id", "YOUR_META_ADS_APP_ID"]
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
## Authentication Flow
|
|
43
|
+
|
|
44
|
+
When using direct Meta OAuth, the MCP uses Meta's OAuth 2.0 authentication flow:
|
|
45
|
+
|
|
46
|
+
1. Starts a local callback server on your machine
|
|
47
|
+
2. Opens a browser window to authenticate with Meta
|
|
48
|
+
3. Asks you to authorize the app
|
|
49
|
+
4. Redirects back to the local server to extract and store the token securely
|
|
50
|
+
|
|
51
|
+
## Environment Variables
|
|
52
|
+
|
|
53
|
+
You can use these environment variables instead of command-line arguments:
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
# Your Meta App ID
|
|
57
|
+
export META_APP_ID=your_app_id
|
|
58
|
+
uvx meta-ads-mcp
|
|
59
|
+
|
|
60
|
+
# Or provide a direct access token (bypasses local cache)
|
|
61
|
+
export META_ACCESS_TOKEN=your_access_token
|
|
62
|
+
uvx meta-ads-mcp
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Testing
|
|
66
|
+
|
|
67
|
+
### CLI Testing
|
|
68
|
+
|
|
69
|
+
Run the test script to verify authentication:
|
|
70
|
+
|
|
71
|
+
```bash
|
|
72
|
+
# Basic test
|
|
73
|
+
python test_meta_ads_auth.py --app-id YOUR_APP_ID
|
|
74
|
+
|
|
75
|
+
# Force new login
|
|
76
|
+
python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### LLM Interface Testing
|
|
80
|
+
|
|
81
|
+
When using direct Meta authentication:
|
|
82
|
+
1. Test authentication by calling the `mcp_meta_ads_get_login_link` tool
|
|
83
|
+
2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
|
|
84
|
+
3. Check specific account details with `mcp_meta_ads_get_account_info`
|
|
85
|
+
|
|
86
|
+
## Troubleshooting
|
|
87
|
+
|
|
88
|
+
### Authentication Issues
|
|
89
|
+
|
|
90
|
+
1. App ID Issues
|
|
91
|
+
- If you encounter errors like `(#200) Provide valid app ID`, verify your App ID is correct
|
|
92
|
+
- Make sure you've completed the app setup steps above
|
|
93
|
+
- Check that your app has the Marketing API product added
|
|
94
|
+
|
|
95
|
+
2. OAuth Flow
|
|
96
|
+
- Run with `--force-login` to get a fresh token: `uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login`
|
|
97
|
+
- Make sure the terminal has permissions to open a browser window
|
|
98
|
+
- Check that the callback server can run on port 8888
|
|
99
|
+
|
|
100
|
+
3. Direct Token Usage
|
|
101
|
+
- If you have a valid access token, you can bypass the OAuth flow:
|
|
102
|
+
- `export META_ACCESS_TOKEN=your_access_token`
|
|
103
|
+
- This will ignore the local token cache
|
|
104
|
+
|
|
105
|
+
### API Errors
|
|
106
|
+
|
|
107
|
+
If you receive errors from the Meta API:
|
|
108
|
+
1. Verify your app has the Marketing API product added
|
|
109
|
+
2. Ensure the user has appropriate permissions on the ad accounts
|
|
110
|
+
3. Check if there are rate limits or other restrictions on your app
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: meta-ads-mcp
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.7
|
|
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.
|
|
14
|
+
Requires-Python: >=3.10
|
|
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
|
|
@@ -31,6 +31,28 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
|
|
|
31
31
|
|
|
32
32
|
|
|
33
33
|
|
|
34
|
+
## Quick Start
|
|
35
|
+
|
|
36
|
+
1. Sign-up to [Pipeboard](https://pipeboard.co) to authenticate with Meta (alternatively, you can setup your own [custom meta app](CUSTOM_META_APP.md))
|
|
37
|
+
2. Get your Pipeboard token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens)
|
|
38
|
+
3. Add this configuration to your MCP client:
|
|
39
|
+
|
|
40
|
+
```json
|
|
41
|
+
"mcpServers": {
|
|
42
|
+
"meta-ads": {
|
|
43
|
+
"command": "uvx",
|
|
44
|
+
"args": ["meta-ads-mcp"],
|
|
45
|
+
"env": {
|
|
46
|
+
"PIPEBOARD_API_TOKEN": "your_pipeboard_token" // Get your token at https://pipeboard.co/api-tokens
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
}
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
That's it! You can now use Meta Ads MCP in your favorite MCP client.
|
|
53
|
+
|
|
54
|
+
> **Note**: If you prefer to use your own Meta Developer App instead of Pipeboard authentication, see [CUSTOM_META_APP.md](CUSTOM_META_APP.md) for instructions.
|
|
55
|
+
|
|
34
56
|
## Features
|
|
35
57
|
|
|
36
58
|
- **AI-Powered Campaign Analysis**: Let your favorite LLM analyze your campaigns and provide actionable insights on performance
|
|
@@ -44,56 +66,80 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
|
|
|
44
66
|
- **Simple Authentication**: Easy setup with secure OAuth authentication
|
|
45
67
|
- **Cross-Platform Support**: Works on Windows, macOS, and Linux
|
|
46
68
|
|
|
47
|
-
##
|
|
69
|
+
## Advanced Setup
|
|
48
70
|
|
|
49
|
-
###
|
|
71
|
+
### Development Installation
|
|
50
72
|
|
|
51
|
-
|
|
73
|
+
If you're contributing to the project or need to run it directly:
|
|
52
74
|
|
|
53
75
|
```bash
|
|
54
|
-
#
|
|
55
|
-
|
|
76
|
+
# From the repository root
|
|
77
|
+
uv pip install -e .
|
|
56
78
|
```
|
|
57
79
|
|
|
58
|
-
|
|
80
|
+
## Privacy and Security
|
|
59
81
|
|
|
60
|
-
|
|
61
|
-
uv pip install meta-ads-mcp
|
|
62
|
-
```
|
|
82
|
+
The Meta Ads MCP follows security best practices:
|
|
63
83
|
|
|
64
|
-
|
|
84
|
+
1. Tokens are cached in a platform-specific secure location:
|
|
85
|
+
- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
|
|
86
|
+
- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
|
|
87
|
+
- Linux: `~/.config/meta-ads-mcp/token_cache.json`
|
|
65
88
|
|
|
66
|
-
|
|
67
|
-
# From the repository root
|
|
68
|
-
uv pip install -e .
|
|
69
|
-
```
|
|
89
|
+
2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
|
|
70
90
|
|
|
71
|
-
|
|
91
|
+
## Testing
|
|
72
92
|
|
|
73
|
-
|
|
93
|
+
### LLM Interface Testing
|
|
74
94
|
|
|
75
|
-
|
|
76
|
-
pip install meta-ads-mcp
|
|
77
|
-
```
|
|
95
|
+
When using the Meta Ads MCP with an LLM interface (like Claude):
|
|
78
96
|
|
|
79
|
-
|
|
97
|
+
1. Ensure the PIPEBOARD_API_TOKEN environment variable is set
|
|
98
|
+
2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
|
|
99
|
+
3. Check specific account details with `mcp_meta_ads_get_account_info`
|
|
80
100
|
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
101
|
+
## Troubleshooting
|
|
102
|
+
|
|
103
|
+
### Authentication Issues
|
|
104
|
+
|
|
105
|
+
If you encounter authentication issues:
|
|
106
|
+
|
|
107
|
+
1. Verify your Pipeboard setup:
|
|
108
|
+
- Check that `PIPEBOARD_API_TOKEN` is set correctly
|
|
109
|
+
- Verify your token in the Pipeboard dashboard
|
|
110
|
+
- Try forcing a new login: `python test_pipeboard_auth.py --force-login`
|
|
111
|
+
|
|
112
|
+
2. When using the LLM interface:
|
|
113
|
+
- Ensure the PIPEBOARD_API_TOKEN environment variable is set
|
|
114
|
+
- Check that the callback server is running properly
|
|
115
|
+
|
|
116
|
+
### API Errors
|
|
117
|
+
|
|
118
|
+
If you receive errors from the Meta API:
|
|
119
|
+
1. Ensure the user has appropriate permissions on the ad accounts
|
|
120
|
+
2. Check if there are rate limits or other restrictions
|
|
121
|
+
3. Verify your Pipeboard token hasn't expired
|
|
122
|
+
|
|
123
|
+
## Log Location
|
|
124
|
+
|
|
125
|
+
Log files are stored in a platform-specific location:
|
|
126
|
+
|
|
127
|
+
- **macOS**: `~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log`
|
|
128
|
+
- **Windows**: `%APPDATA%\meta-ads-mcp\meta_ads_debug.log`
|
|
129
|
+
- **Linux**: `~/.config/meta-ads-mcp/meta_ads_debug.log`
|
|
85
130
|
|
|
86
131
|
## Configuration
|
|
87
132
|
|
|
88
|
-
###
|
|
133
|
+
### Pipeboard Authentication
|
|
89
134
|
|
|
90
|
-
|
|
135
|
+
The easiest way to use Meta Ads MCP is with Pipeboard authentication:
|
|
91
136
|
|
|
92
|
-
1.
|
|
93
|
-
2.
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
137
|
+
1. Sign up at [Pipeboard.co](https://pipeboard.co) and generate an API token
|
|
138
|
+
2. Set the environment variable:
|
|
139
|
+
```bash
|
|
140
|
+
export PIPEBOARD_API_TOKEN=your_pipeboard_token
|
|
141
|
+
```
|
|
142
|
+
3. Run meta-ads-mcp - it will handle authentication automatically
|
|
97
143
|
|
|
98
144
|
### Usage with Cursor or Claude Desktop
|
|
99
145
|
|
|
@@ -103,7 +149,10 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
|
|
|
103
149
|
"mcpServers": {
|
|
104
150
|
"meta-ads": {
|
|
105
151
|
"command": "uvx",
|
|
106
|
-
"args": ["meta-ads-mcp",
|
|
152
|
+
"args": ["meta-ads-mcp"],
|
|
153
|
+
"env": {
|
|
154
|
+
"PIPEBOARD_API_TOKEN": "your_pipeboard_token" // Get your token at https://pipeboard.co
|
|
155
|
+
}
|
|
107
156
|
}
|
|
108
157
|
}
|
|
109
158
|
```
|
|
@@ -319,157 +368,3 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
|
|
|
319
368
|
- `time_end`: Unix timestamp for when the high demand period should end.
|
|
320
369
|
- `access_token` (optional): Meta API access token.
|
|
321
370
|
- Returns: JSON string with the ID of the created budget schedule or an error message.
|
|
322
|
-
|
|
323
|
-
## Authentication
|
|
324
|
-
|
|
325
|
-
The Meta Ads MCP uses Meta's OAuth 2.0 authentication flow, designed for desktop apps:
|
|
326
|
-
|
|
327
|
-
When authenticating, it will:
|
|
328
|
-
|
|
329
|
-
1. Start a local callback server on your machine
|
|
330
|
-
2. Open a browser window to authenticate with Meta
|
|
331
|
-
3. Ask you to authorize the app
|
|
332
|
-
4. Redirect back to the local server to extract and store the token securely
|
|
333
|
-
|
|
334
|
-
This method requires you to [create a Meta Developer App](#create-a-meta-developer-app) as described above.
|
|
335
|
-
|
|
336
|
-
## Troubleshooting and Logging
|
|
337
|
-
|
|
338
|
-
The Meta Ads MCP includes a comprehensive logging system to help troubleshoot issues:
|
|
339
|
-
|
|
340
|
-
### Log Location
|
|
341
|
-
|
|
342
|
-
Log files are stored in a platform-specific location:
|
|
343
|
-
|
|
344
|
-
- **macOS**: `~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log`
|
|
345
|
-
- **Windows**: `%APPDATA%\meta-ads-mcp\meta_ads_debug.log`
|
|
346
|
-
- **Linux**: `~/.config/meta-ads-mcp/meta_ads_debug.log`
|
|
347
|
-
|
|
348
|
-
### Common Issues
|
|
349
|
-
|
|
350
|
-
#### Authentication Issues
|
|
351
|
-
|
|
352
|
-
If you encounter errors like `(#200) Provide valid app ID`, check the following:
|
|
353
|
-
- Ensure you've set up a Meta Developer App correctly
|
|
354
|
-
- Verify that you're passing the correct App ID using one of these methods:
|
|
355
|
-
- Set the `META_APP_ID` environment variable: `export META_APP_ID=your_app_id`
|
|
356
|
-
- Pass it as a command-line argument: `meta-ads-mcp --app-id your_app_id`
|
|
357
|
-
|
|
358
|
-
#### API Errors
|
|
359
|
-
|
|
360
|
-
If you receive errors from the Meta API:
|
|
361
|
-
|
|
362
|
-
1. Verify your app has the Marketing API product added
|
|
363
|
-
2. Ensure the user has appropriate permissions on the ad accounts
|
|
364
|
-
3. Check if there are rate limits or other restrictions on your app
|
|
365
|
-
|
|
366
|
-
### Debugging Command
|
|
367
|
-
|
|
368
|
-
For specific image download issues, use the built-in diagnostic tool:
|
|
369
|
-
|
|
370
|
-
```python
|
|
371
|
-
# Using direct tool call
|
|
372
|
-
mcp_meta_ads_debug_image_download(ad_id="your_ad_id")
|
|
373
|
-
```
|
|
374
|
-
|
|
375
|
-
This will give you detailed information about the download process and potential issues.
|
|
376
|
-
|
|
377
|
-
## Running with Different App IDs
|
|
378
|
-
|
|
379
|
-
If you need to use different Meta App IDs for different purposes:
|
|
380
|
-
|
|
381
|
-
```bash
|
|
382
|
-
# Using environment variable
|
|
383
|
-
export META_APP_ID=your_app_id
|
|
384
|
-
uvx meta-ads-mcp
|
|
385
|
-
|
|
386
|
-
# Or using command line argument
|
|
387
|
-
uvx meta-ads-mcp --app-id=your_app_id
|
|
388
|
-
```
|
|
389
|
-
|
|
390
|
-
## Privacy and Security
|
|
391
|
-
|
|
392
|
-
The Meta Ads MCP follows security best practices:
|
|
393
|
-
|
|
394
|
-
1. Tokens are cached in a platform-specific secure location:
|
|
395
|
-
- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
|
|
396
|
-
- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
|
|
397
|
-
- Linux: `~/.config/meta-ads-mcp/token_cache.json`
|
|
398
|
-
|
|
399
|
-
2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
|
|
400
|
-
|
|
401
|
-
3. You can set the `META_APP_ID` environment variable instead of passing it as an argument:
|
|
402
|
-
```bash
|
|
403
|
-
export META_APP_ID=your_app_id
|
|
404
|
-
uvx meta-ads-mcp
|
|
405
|
-
```
|
|
406
|
-
|
|
407
|
-
4. You can provide a direct access token using the `META_ACCESS_TOKEN` environment variable. This bypasses both the local token cache and the Pipeboard authentication method:
|
|
408
|
-
```bash
|
|
409
|
-
export META_ACCESS_TOKEN=your_access_token
|
|
410
|
-
uvx meta-ads-mcp
|
|
411
|
-
```
|
|
412
|
-
This is useful for CI/CD pipelines or when you already have a valid access token from another source.
|
|
413
|
-
|
|
414
|
-
## Testing
|
|
415
|
-
|
|
416
|
-
### CLI Testing
|
|
417
|
-
|
|
418
|
-
Run the test script to verify authentication and basic functionality:
|
|
419
|
-
|
|
420
|
-
```bash
|
|
421
|
-
python test_meta_ads_auth.py --app-id YOUR_APP_ID
|
|
422
|
-
```
|
|
423
|
-
|
|
424
|
-
Use the `--force-login` flag to force a new authentication even if a cached token exists:
|
|
425
|
-
|
|
426
|
-
```bash
|
|
427
|
-
python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
|
|
428
|
-
```
|
|
429
|
-
|
|
430
|
-
### LLM Interface Testing
|
|
431
|
-
|
|
432
|
-
When using the Meta Ads MCP with an LLM interface (like Claude):
|
|
433
|
-
|
|
434
|
-
1. Test authentication by calling the `mcp_meta_ads_get_login_link` tool
|
|
435
|
-
2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
|
|
436
|
-
3. Check specific account details with `mcp_meta_ads_get_account_info`
|
|
437
|
-
|
|
438
|
-
These functions will automatically handle authentication if needed and provide a clickable login link if required.
|
|
439
|
-
|
|
440
|
-
## Troubleshooting
|
|
441
|
-
|
|
442
|
-
### Authentication Issues
|
|
443
|
-
|
|
444
|
-
If you encounter authentication issues:
|
|
445
|
-
|
|
446
|
-
1. When using the LLM interface:
|
|
447
|
-
- Use the `mcp_meta_ads_get_login_link` tool to generate a fresh authentication link
|
|
448
|
-
- Ensure you click the link and complete the authorization flow in your browser
|
|
449
|
-
- Check that the callback server is running properly (the tool will report this)
|
|
450
|
-
|
|
451
|
-
2. When using direct Meta OAuth:
|
|
452
|
-
- Run with `--force-login` to get a fresh token: `uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login`
|
|
453
|
-
- Make sure the terminal has permissions to open a browser window
|
|
454
|
-
|
|
455
|
-
3. Skip authentication entirely by providing a token directly:
|
|
456
|
-
- If you already have a valid access token, you can bypass the authentication flow:
|
|
457
|
-
- `export META_ACCESS_TOKEN=your_access_token`
|
|
458
|
-
- This will ignore both the local token cache and the Pipeboard authentication
|
|
459
|
-
|
|
460
|
-
### API Errors
|
|
461
|
-
|
|
462
|
-
If you receive errors from the Meta API:
|
|
463
|
-
|
|
464
|
-
1. Verify your app has the Marketing API product added
|
|
465
|
-
2. Ensure the user has appropriate permissions on the ad accounts
|
|
466
|
-
3. Check if there are rate limits or other restrictions on your app
|
|
467
|
-
|
|
468
|
-
## Versioning
|
|
469
|
-
|
|
470
|
-
You can check the current version of the package:
|
|
471
|
-
|
|
472
|
-
```python
|
|
473
|
-
import meta_ads_mcp
|
|
474
|
-
print(meta_ads_mcp.__version__)
|
|
475
|
-
```
|
|
@@ -8,6 +8,28 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
|
|
|
8
8
|
|
|
9
9
|
|
|
10
10
|
|
|
11
|
+
## Quick Start
|
|
12
|
+
|
|
13
|
+
1. Sign-up to [Pipeboard](https://pipeboard.co) to authenticate with Meta (alternatively, you can setup your own [custom meta app](CUSTOM_META_APP.md))
|
|
14
|
+
2. Get your Pipeboard token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens)
|
|
15
|
+
3. Add this configuration to your MCP client:
|
|
16
|
+
|
|
17
|
+
```json
|
|
18
|
+
"mcpServers": {
|
|
19
|
+
"meta-ads": {
|
|
20
|
+
"command": "uvx",
|
|
21
|
+
"args": ["meta-ads-mcp"],
|
|
22
|
+
"env": {
|
|
23
|
+
"PIPEBOARD_API_TOKEN": "your_pipeboard_token" // Get your token at https://pipeboard.co/api-tokens
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
}
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
That's it! You can now use Meta Ads MCP in your favorite MCP client.
|
|
30
|
+
|
|
31
|
+
> **Note**: If you prefer to use your own Meta Developer App instead of Pipeboard authentication, see [CUSTOM_META_APP.md](CUSTOM_META_APP.md) for instructions.
|
|
32
|
+
|
|
11
33
|
## Features
|
|
12
34
|
|
|
13
35
|
- **AI-Powered Campaign Analysis**: Let your favorite LLM analyze your campaigns and provide actionable insights on performance
|
|
@@ -21,56 +43,80 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
|
|
|
21
43
|
- **Simple Authentication**: Easy setup with secure OAuth authentication
|
|
22
44
|
- **Cross-Platform Support**: Works on Windows, macOS, and Linux
|
|
23
45
|
|
|
24
|
-
##
|
|
46
|
+
## Advanced Setup
|
|
25
47
|
|
|
26
|
-
###
|
|
48
|
+
### Development Installation
|
|
27
49
|
|
|
28
|
-
|
|
50
|
+
If you're contributing to the project or need to run it directly:
|
|
29
51
|
|
|
30
52
|
```bash
|
|
31
|
-
#
|
|
32
|
-
|
|
53
|
+
# From the repository root
|
|
54
|
+
uv pip install -e .
|
|
33
55
|
```
|
|
34
56
|
|
|
35
|
-
|
|
57
|
+
## Privacy and Security
|
|
36
58
|
|
|
37
|
-
|
|
38
|
-
uv pip install meta-ads-mcp
|
|
39
|
-
```
|
|
59
|
+
The Meta Ads MCP follows security best practices:
|
|
40
60
|
|
|
41
|
-
|
|
61
|
+
1. Tokens are cached in a platform-specific secure location:
|
|
62
|
+
- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
|
|
63
|
+
- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
|
|
64
|
+
- Linux: `~/.config/meta-ads-mcp/token_cache.json`
|
|
42
65
|
|
|
43
|
-
|
|
44
|
-
# From the repository root
|
|
45
|
-
uv pip install -e .
|
|
46
|
-
```
|
|
66
|
+
2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
|
|
47
67
|
|
|
48
|
-
|
|
68
|
+
## Testing
|
|
49
69
|
|
|
50
|
-
|
|
70
|
+
### LLM Interface Testing
|
|
51
71
|
|
|
52
|
-
|
|
53
|
-
pip install meta-ads-mcp
|
|
54
|
-
```
|
|
72
|
+
When using the Meta Ads MCP with an LLM interface (like Claude):
|
|
55
73
|
|
|
56
|
-
|
|
74
|
+
1. Ensure the PIPEBOARD_API_TOKEN environment variable is set
|
|
75
|
+
2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
|
|
76
|
+
3. Check specific account details with `mcp_meta_ads_get_account_info`
|
|
57
77
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
78
|
+
## Troubleshooting
|
|
79
|
+
|
|
80
|
+
### Authentication Issues
|
|
81
|
+
|
|
82
|
+
If you encounter authentication issues:
|
|
83
|
+
|
|
84
|
+
1. Verify your Pipeboard setup:
|
|
85
|
+
- Check that `PIPEBOARD_API_TOKEN` is set correctly
|
|
86
|
+
- Verify your token in the Pipeboard dashboard
|
|
87
|
+
- Try forcing a new login: `python test_pipeboard_auth.py --force-login`
|
|
88
|
+
|
|
89
|
+
2. When using the LLM interface:
|
|
90
|
+
- Ensure the PIPEBOARD_API_TOKEN environment variable is set
|
|
91
|
+
- Check that the callback server is running properly
|
|
92
|
+
|
|
93
|
+
### API Errors
|
|
94
|
+
|
|
95
|
+
If you receive errors from the Meta API:
|
|
96
|
+
1. Ensure the user has appropriate permissions on the ad accounts
|
|
97
|
+
2. Check if there are rate limits or other restrictions
|
|
98
|
+
3. Verify your Pipeboard token hasn't expired
|
|
99
|
+
|
|
100
|
+
## Log Location
|
|
101
|
+
|
|
102
|
+
Log files are stored in a platform-specific location:
|
|
103
|
+
|
|
104
|
+
- **macOS**: `~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log`
|
|
105
|
+
- **Windows**: `%APPDATA%\meta-ads-mcp\meta_ads_debug.log`
|
|
106
|
+
- **Linux**: `~/.config/meta-ads-mcp/meta_ads_debug.log`
|
|
62
107
|
|
|
63
108
|
## Configuration
|
|
64
109
|
|
|
65
|
-
###
|
|
110
|
+
### Pipeboard Authentication
|
|
66
111
|
|
|
67
|
-
|
|
112
|
+
The easiest way to use Meta Ads MCP is with Pipeboard authentication:
|
|
68
113
|
|
|
69
|
-
1.
|
|
70
|
-
2.
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
114
|
+
1. Sign up at [Pipeboard.co](https://pipeboard.co) and generate an API token
|
|
115
|
+
2. Set the environment variable:
|
|
116
|
+
```bash
|
|
117
|
+
export PIPEBOARD_API_TOKEN=your_pipeboard_token
|
|
118
|
+
```
|
|
119
|
+
3. Run meta-ads-mcp - it will handle authentication automatically
|
|
74
120
|
|
|
75
121
|
### Usage with Cursor or Claude Desktop
|
|
76
122
|
|
|
@@ -80,7 +126,10 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
|
|
|
80
126
|
"mcpServers": {
|
|
81
127
|
"meta-ads": {
|
|
82
128
|
"command": "uvx",
|
|
83
|
-
"args": ["meta-ads-mcp",
|
|
129
|
+
"args": ["meta-ads-mcp"],
|
|
130
|
+
"env": {
|
|
131
|
+
"PIPEBOARD_API_TOKEN": "your_pipeboard_token" // Get your token at https://pipeboard.co
|
|
132
|
+
}
|
|
84
133
|
}
|
|
85
134
|
}
|
|
86
135
|
```
|
|
@@ -296,157 +345,3 @@ Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cu
|
|
|
296
345
|
- `time_end`: Unix timestamp for when the high demand period should end.
|
|
297
346
|
- `access_token` (optional): Meta API access token.
|
|
298
347
|
- Returns: JSON string with the ID of the created budget schedule or an error message.
|
|
299
|
-
|
|
300
|
-
## Authentication
|
|
301
|
-
|
|
302
|
-
The Meta Ads MCP uses Meta's OAuth 2.0 authentication flow, designed for desktop apps:
|
|
303
|
-
|
|
304
|
-
When authenticating, it will:
|
|
305
|
-
|
|
306
|
-
1. Start a local callback server on your machine
|
|
307
|
-
2. Open a browser window to authenticate with Meta
|
|
308
|
-
3. Ask you to authorize the app
|
|
309
|
-
4. Redirect back to the local server to extract and store the token securely
|
|
310
|
-
|
|
311
|
-
This method requires you to [create a Meta Developer App](#create-a-meta-developer-app) as described above.
|
|
312
|
-
|
|
313
|
-
## Troubleshooting and Logging
|
|
314
|
-
|
|
315
|
-
The Meta Ads MCP includes a comprehensive logging system to help troubleshoot issues:
|
|
316
|
-
|
|
317
|
-
### Log Location
|
|
318
|
-
|
|
319
|
-
Log files are stored in a platform-specific location:
|
|
320
|
-
|
|
321
|
-
- **macOS**: `~/Library/Application Support/meta-ads-mcp/meta_ads_debug.log`
|
|
322
|
-
- **Windows**: `%APPDATA%\meta-ads-mcp\meta_ads_debug.log`
|
|
323
|
-
- **Linux**: `~/.config/meta-ads-mcp/meta_ads_debug.log`
|
|
324
|
-
|
|
325
|
-
### Common Issues
|
|
326
|
-
|
|
327
|
-
#### Authentication Issues
|
|
328
|
-
|
|
329
|
-
If you encounter errors like `(#200) Provide valid app ID`, check the following:
|
|
330
|
-
- Ensure you've set up a Meta Developer App correctly
|
|
331
|
-
- Verify that you're passing the correct App ID using one of these methods:
|
|
332
|
-
- Set the `META_APP_ID` environment variable: `export META_APP_ID=your_app_id`
|
|
333
|
-
- Pass it as a command-line argument: `meta-ads-mcp --app-id your_app_id`
|
|
334
|
-
|
|
335
|
-
#### API Errors
|
|
336
|
-
|
|
337
|
-
If you receive errors from the Meta API:
|
|
338
|
-
|
|
339
|
-
1. Verify your app has the Marketing API product added
|
|
340
|
-
2. Ensure the user has appropriate permissions on the ad accounts
|
|
341
|
-
3. Check if there are rate limits or other restrictions on your app
|
|
342
|
-
|
|
343
|
-
### Debugging Command
|
|
344
|
-
|
|
345
|
-
For specific image download issues, use the built-in diagnostic tool:
|
|
346
|
-
|
|
347
|
-
```python
|
|
348
|
-
# Using direct tool call
|
|
349
|
-
mcp_meta_ads_debug_image_download(ad_id="your_ad_id")
|
|
350
|
-
```
|
|
351
|
-
|
|
352
|
-
This will give you detailed information about the download process and potential issues.
|
|
353
|
-
|
|
354
|
-
## Running with Different App IDs
|
|
355
|
-
|
|
356
|
-
If you need to use different Meta App IDs for different purposes:
|
|
357
|
-
|
|
358
|
-
```bash
|
|
359
|
-
# Using environment variable
|
|
360
|
-
export META_APP_ID=your_app_id
|
|
361
|
-
uvx meta-ads-mcp
|
|
362
|
-
|
|
363
|
-
# Or using command line argument
|
|
364
|
-
uvx meta-ads-mcp --app-id=your_app_id
|
|
365
|
-
```
|
|
366
|
-
|
|
367
|
-
## Privacy and Security
|
|
368
|
-
|
|
369
|
-
The Meta Ads MCP follows security best practices:
|
|
370
|
-
|
|
371
|
-
1. Tokens are cached in a platform-specific secure location:
|
|
372
|
-
- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
|
|
373
|
-
- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
|
|
374
|
-
- Linux: `~/.config/meta-ads-mcp/token_cache.json`
|
|
375
|
-
|
|
376
|
-
2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
|
|
377
|
-
|
|
378
|
-
3. You can set the `META_APP_ID` environment variable instead of passing it as an argument:
|
|
379
|
-
```bash
|
|
380
|
-
export META_APP_ID=your_app_id
|
|
381
|
-
uvx meta-ads-mcp
|
|
382
|
-
```
|
|
383
|
-
|
|
384
|
-
4. You can provide a direct access token using the `META_ACCESS_TOKEN` environment variable. This bypasses both the local token cache and the Pipeboard authentication method:
|
|
385
|
-
```bash
|
|
386
|
-
export META_ACCESS_TOKEN=your_access_token
|
|
387
|
-
uvx meta-ads-mcp
|
|
388
|
-
```
|
|
389
|
-
This is useful for CI/CD pipelines or when you already have a valid access token from another source.
|
|
390
|
-
|
|
391
|
-
## Testing
|
|
392
|
-
|
|
393
|
-
### CLI Testing
|
|
394
|
-
|
|
395
|
-
Run the test script to verify authentication and basic functionality:
|
|
396
|
-
|
|
397
|
-
```bash
|
|
398
|
-
python test_meta_ads_auth.py --app-id YOUR_APP_ID
|
|
399
|
-
```
|
|
400
|
-
|
|
401
|
-
Use the `--force-login` flag to force a new authentication even if a cached token exists:
|
|
402
|
-
|
|
403
|
-
```bash
|
|
404
|
-
python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
|
|
405
|
-
```
|
|
406
|
-
|
|
407
|
-
### LLM Interface Testing
|
|
408
|
-
|
|
409
|
-
When using the Meta Ads MCP with an LLM interface (like Claude):
|
|
410
|
-
|
|
411
|
-
1. Test authentication by calling the `mcp_meta_ads_get_login_link` tool
|
|
412
|
-
2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
|
|
413
|
-
3. Check specific account details with `mcp_meta_ads_get_account_info`
|
|
414
|
-
|
|
415
|
-
These functions will automatically handle authentication if needed and provide a clickable login link if required.
|
|
416
|
-
|
|
417
|
-
## Troubleshooting
|
|
418
|
-
|
|
419
|
-
### Authentication Issues
|
|
420
|
-
|
|
421
|
-
If you encounter authentication issues:
|
|
422
|
-
|
|
423
|
-
1. When using the LLM interface:
|
|
424
|
-
- Use the `mcp_meta_ads_get_login_link` tool to generate a fresh authentication link
|
|
425
|
-
- Ensure you click the link and complete the authorization flow in your browser
|
|
426
|
-
- Check that the callback server is running properly (the tool will report this)
|
|
427
|
-
|
|
428
|
-
2. When using direct Meta OAuth:
|
|
429
|
-
- Run with `--force-login` to get a fresh token: `uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login`
|
|
430
|
-
- Make sure the terminal has permissions to open a browser window
|
|
431
|
-
|
|
432
|
-
3. Skip authentication entirely by providing a token directly:
|
|
433
|
-
- If you already have a valid access token, you can bypass the authentication flow:
|
|
434
|
-
- `export META_ACCESS_TOKEN=your_access_token`
|
|
435
|
-
- This will ignore both the local token cache and the Pipeboard authentication
|
|
436
|
-
|
|
437
|
-
### API Errors
|
|
438
|
-
|
|
439
|
-
If you receive errors from the Meta API:
|
|
440
|
-
|
|
441
|
-
1. Verify your app has the Marketing API product added
|
|
442
|
-
2. Ensure the user has appropriate permissions on the ad accounts
|
|
443
|
-
3. Check if there are rate limits or other restrictions on your app
|
|
444
|
-
|
|
445
|
-
## Versioning
|
|
446
|
-
|
|
447
|
-
You can check the current version of the package:
|
|
448
|
-
|
|
449
|
-
```python
|
|
450
|
-
import meta_ads_mcp
|
|
451
|
-
print(meta_ads_mcp.__version__)
|
|
452
|
-
```
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
# Release Process
|
|
2
|
+
|
|
3
|
+
This repository uses GitHub Actions to automatically publish releases to PyPI. Here's how it works:
|
|
4
|
+
|
|
5
|
+
## Automated Publishing
|
|
6
|
+
|
|
7
|
+
### Setup Required
|
|
8
|
+
|
|
9
|
+
1. **Configure Trusted Publishing on PyPI** (Recommended):
|
|
10
|
+
- Go to your PyPI project page: https://pypi.org/manage/project/meta-ads-mcp/
|
|
11
|
+
- Navigate to "Publishing" → "Add a new pending publisher"
|
|
12
|
+
- Fill in the details:
|
|
13
|
+
- Owner: `nictuku` (your GitHub username/org)
|
|
14
|
+
- Repository name: `meta-ads-mcp`
|
|
15
|
+
- Workflow name: `publish.yml`
|
|
16
|
+
- Environment name: `release`
|
|
17
|
+
|
|
18
|
+
This eliminates the need for API tokens and is more secure.
|
|
19
|
+
|
|
20
|
+
2. **Alternative: API Token Method**:
|
|
21
|
+
- If you prefer using API tokens, go to PyPI → Account Settings → API tokens
|
|
22
|
+
- Create a token with scope limited to this project
|
|
23
|
+
- Add it as a repository secret named `PYPI_API_TOKEN`
|
|
24
|
+
- Modify `.github/workflows/publish.yml` to use the token instead of trusted publishing
|
|
25
|
+
|
|
26
|
+
### Creating a Release
|
|
27
|
+
|
|
28
|
+
1. **Update the version** in `pyproject.toml`:
|
|
29
|
+
```toml
|
|
30
|
+
version = "0.3.8" # Increment as needed
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
2. **Commit and push** the version change:
|
|
34
|
+
```bash
|
|
35
|
+
git add pyproject.toml
|
|
36
|
+
git commit -m "Bump version to 0.3.8"
|
|
37
|
+
git push origin main
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
3. **Create a GitHub release**:
|
|
41
|
+
- Go to https://github.com/nictuku/meta-ads-mcp/releases
|
|
42
|
+
- Click "Create a new release"
|
|
43
|
+
- Tag version: `v0.3.8` (must match the version in pyproject.toml)
|
|
44
|
+
- Release title: `v0.3.8`
|
|
45
|
+
- Add release notes describing what changed
|
|
46
|
+
- Click "Publish release"
|
|
47
|
+
|
|
48
|
+
4. **Automatic deployment**:
|
|
49
|
+
- The GitHub Action will automatically trigger
|
|
50
|
+
- It will build the package and publish to PyPI
|
|
51
|
+
- Check the "Actions" tab to monitor progress
|
|
52
|
+
|
|
53
|
+
## Workflows
|
|
54
|
+
|
|
55
|
+
### `publish.yml`
|
|
56
|
+
- **Triggers**: When a GitHub release is published
|
|
57
|
+
- **Purpose**: Builds and publishes the package to PyPI
|
|
58
|
+
- **Environment**: Uses the `release` environment for additional security
|
|
59
|
+
|
|
60
|
+
### `test.yml`
|
|
61
|
+
- **Triggers**: On pushes and pull requests to main/master
|
|
62
|
+
- **Purpose**: Tests package building and installation across Python versions
|
|
63
|
+
- **Matrix**: Tests Python 3.10, 3.11, and 3.12
|
|
64
|
+
|
|
65
|
+
## Manual Deployment
|
|
66
|
+
|
|
67
|
+
If you need to deploy manually:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
# Install build tools
|
|
71
|
+
pip install build twine
|
|
72
|
+
|
|
73
|
+
# Build the package
|
|
74
|
+
python -m build
|
|
75
|
+
|
|
76
|
+
# Upload to PyPI (requires API token or configured credentials)
|
|
77
|
+
python -m twine upload dist/*
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
## Version Management
|
|
81
|
+
|
|
82
|
+
- Follow semantic versioning (SemVer): `MAJOR.MINOR.PATCH`
|
|
83
|
+
- Update version in `pyproject.toml` before creating releases
|
|
84
|
+
- The git tag should match the version (e.g., `v0.3.8` for version `0.3.8`)
|
|
85
|
+
|
|
86
|
+
## Security Notes
|
|
87
|
+
|
|
88
|
+
- Trusted publishing is preferred over API tokens
|
|
89
|
+
- The `release` environment can be configured with additional protection rules
|
|
90
|
+
- Only maintainers should be able to create releases
|
|
91
|
+
- All builds run in isolated GitHub-hosted runners
|
|
@@ -767,7 +767,7 @@ async def get_account_info(access_token: str = None, account_id: str = None) ->
|
|
|
767
767
|
|
|
768
768
|
@mcp_server.tool()
|
|
769
769
|
@meta_api_tool
|
|
770
|
-
async def get_campaigns(access_token: str = None, account_id: str = None, limit: int = 10, status_filter: str = "") -> str:
|
|
770
|
+
async def get_campaigns(access_token: str = None, account_id: str = None, limit: int = 10, status_filter: str = "", after: str = "") -> str:
|
|
771
771
|
"""
|
|
772
772
|
Get campaigns for a Meta Ads account with optional filtering.
|
|
773
773
|
|
|
@@ -776,6 +776,7 @@ async def get_campaigns(access_token: str = None, account_id: str = None, limit:
|
|
|
776
776
|
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
|
|
777
777
|
limit: Maximum number of campaigns to return (default: 10)
|
|
778
778
|
status_filter: Filter by status (empty for all, or 'ACTIVE', 'PAUSED', etc.)
|
|
779
|
+
after: Pagination cursor to get the next set of results
|
|
779
780
|
"""
|
|
780
781
|
# If no account ID is specified, try to get the first one for the user
|
|
781
782
|
if not account_id:
|
|
@@ -796,6 +797,9 @@ async def get_campaigns(access_token: str = None, account_id: str = None, limit:
|
|
|
796
797
|
if status_filter:
|
|
797
798
|
params["effective_status"] = [status_filter]
|
|
798
799
|
|
|
800
|
+
if after:
|
|
801
|
+
params["after"] = after
|
|
802
|
+
|
|
799
803
|
data = await make_api_request(endpoint, access_token, params)
|
|
800
804
|
|
|
801
805
|
return json.dumps(data, indent=2)
|
|
@@ -841,7 +845,7 @@ async def create_campaign(
|
|
|
841
845
|
access_token: Meta API access token (optional - will use cached token if not provided)
|
|
842
846
|
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
|
|
843
847
|
name: Campaign name
|
|
844
|
-
objective: Campaign objective
|
|
848
|
+
objective: Campaign objective. enum{BRAND_AWARENESS, LEAD_GENERATION, LINK_CLICKS, CONVERSIONS, OUTCOME_TRAFFIC, etc.}.
|
|
845
849
|
status: Initial campaign status (default: PAUSED)
|
|
846
850
|
special_ad_categories: List of special ad categories if applicable
|
|
847
851
|
daily_budget: Daily budget in account currency (in cents)
|
|
@@ -206,6 +206,9 @@ def meta_api_tool(func):
|
|
|
206
206
|
if (auth_manager.app_id == "YOUR_META_APP_ID" or not auth_manager.app_id) and not auth_manager.use_pipeboard:
|
|
207
207
|
logger.error("TOKEN VALIDATION FAILED: No valid app_id configured")
|
|
208
208
|
logger.error("Please set META_APP_ID environment variable or configure in your code")
|
|
209
|
+
elif auth_manager.use_pipeboard:
|
|
210
|
+
logger.error("TOKEN VALIDATION FAILED: Pipeboard authentication enabled but no valid token available")
|
|
211
|
+
logger.error("Complete authentication via Pipeboard service or check PIPEBOARD_API_TOKEN")
|
|
209
212
|
else:
|
|
210
213
|
logger.error("Check logs above for detailed token validation failures")
|
|
211
214
|
except Exception as e:
|
|
@@ -221,16 +224,21 @@ def meta_api_tool(func):
|
|
|
221
224
|
# Add more specific troubleshooting information
|
|
222
225
|
auth_url = auth_manager.get_auth_url()
|
|
223
226
|
app_id = auth_manager.app_id
|
|
227
|
+
using_pipeboard = auth_manager.use_pipeboard
|
|
224
228
|
|
|
225
229
|
logger.error("TOKEN VALIDATION SUMMARY:")
|
|
226
230
|
logger.error(f"- Current app_id: '{app_id}'")
|
|
227
231
|
logger.error(f"- Environment META_APP_ID: '{os.environ.get('META_APP_ID', 'Not set')}'")
|
|
228
232
|
logger.error(f"- Pipeboard API token configured: {'Yes' if os.environ.get('PIPEBOARD_API_TOKEN') else 'No'}")
|
|
233
|
+
logger.error(f"- Using Pipeboard authentication: {'Yes' if using_pipeboard else 'No'}")
|
|
229
234
|
|
|
230
|
-
# Check for common configuration issues
|
|
231
|
-
if app_id == "YOUR_META_APP_ID" or not app_id:
|
|
235
|
+
# Check for common configuration issues - but only if not using Pipeboard
|
|
236
|
+
if not using_pipeboard and (app_id == "YOUR_META_APP_ID" or not app_id):
|
|
232
237
|
logger.error("ISSUE DETECTED: No valid Meta App ID configured")
|
|
233
238
|
logger.error("ACTION REQUIRED: Set META_APP_ID environment variable with a valid App ID")
|
|
239
|
+
elif using_pipeboard:
|
|
240
|
+
logger.error("ISSUE DETECTED: Pipeboard authentication configured but no valid token available")
|
|
241
|
+
logger.error("ACTION REQUIRED: Complete authentication via Pipeboard service")
|
|
234
242
|
|
|
235
243
|
return json.dumps({
|
|
236
244
|
"error": {
|
|
@@ -116,7 +116,7 @@ async def get_login_link(access_token: str = None) -> str:
|
|
|
116
116
|
"authentication_method": "meta_oauth",
|
|
117
117
|
"token_exchange_message": f"Your authentication token will be valid for approximately {token_duration}." +
|
|
118
118
|
(" Long-lived token exchange is enabled." if token_exchange_supported else
|
|
119
|
-
"
|
|
119
|
+
" For direct Meta authentication, long-lived tokens require META_APP_SECRET. Consider using Pipeboard authentication instead (60-day tokens by default)."),
|
|
120
120
|
"note": "After authenticating, the token will be automatically saved."
|
|
121
121
|
}
|
|
122
122
|
|
|
@@ -9,7 +9,7 @@ from .server import mcp_server
|
|
|
9
9
|
|
|
10
10
|
@mcp_server.tool()
|
|
11
11
|
@meta_api_tool
|
|
12
|
-
async def get_campaigns(access_token: str = None, account_id: str = None, limit: int = 10, status_filter: str = "") -> str:
|
|
12
|
+
async def get_campaigns(access_token: str = None, account_id: str = None, limit: int = 10, status_filter: str = "", after: str = "") -> str:
|
|
13
13
|
"""
|
|
14
14
|
Get campaigns for a Meta Ads account with optional filtering.
|
|
15
15
|
|
|
@@ -26,6 +26,7 @@ async def get_campaigns(access_token: str = None, account_id: str = None, limit:
|
|
|
26
26
|
status_filter: Filter by effective status (e.g., 'ACTIVE', 'PAUSED', 'ARCHIVED').
|
|
27
27
|
Maps to the 'effective_status' API parameter, which expects an array
|
|
28
28
|
(this function handles the required JSON formatting). Leave empty for all statuses.
|
|
29
|
+
after: Pagination cursor to get the next set of results
|
|
29
30
|
"""
|
|
30
31
|
# If no account ID is specified, try to get the first one for the user
|
|
31
32
|
if not account_id:
|
|
@@ -47,6 +48,9 @@ async def get_campaigns(access_token: str = None, account_id: str = None, limit:
|
|
|
47
48
|
# API expects an array, encode it as a JSON string
|
|
48
49
|
params["effective_status"] = json.dumps([status_filter])
|
|
49
50
|
|
|
51
|
+
if after:
|
|
52
|
+
params["after"] = after
|
|
53
|
+
|
|
50
54
|
data = await make_api_request(endpoint, access_token, params)
|
|
51
55
|
|
|
52
56
|
return json.dumps(data, indent=2)
|
|
@@ -104,7 +108,7 @@ async def create_campaign(
|
|
|
104
108
|
access_token: Meta API access token (optional - will use cached token if not provided)
|
|
105
109
|
account_id: Meta Ads account ID (format: act_XXXXXXXXX)
|
|
106
110
|
name: Campaign name
|
|
107
|
-
objective: Campaign objective
|
|
111
|
+
objective: Campaign objective. Validates ad objectives. enum{BRAND_AWARENESS, LEAD_GENERATION, LINK_CLICKS, CONVERSIONS, OUTCOME_TRAFFIC, etc.}.
|
|
108
112
|
status: Initial campaign status (default: PAUSED)
|
|
109
113
|
special_ad_categories: List of special ad categories if applicable
|
|
110
114
|
daily_budget: Daily budget in account currency (in cents) as a string
|
|
@@ -24,9 +24,13 @@ using_pipeboard = bool(os.environ.get("PIPEBOARD_API_TOKEN", ""))
|
|
|
24
24
|
# Print warning if Meta app credentials are not configured and not using Pipeboard
|
|
25
25
|
if not using_pipeboard:
|
|
26
26
|
if not META_APP_ID:
|
|
27
|
-
print("WARNING: META_APP_ID environment variable is not set.
|
|
27
|
+
print("WARNING: META_APP_ID environment variable is not set.")
|
|
28
|
+
print("RECOMMENDED: Use Pipeboard authentication by setting PIPEBOARD_API_TOKEN instead.")
|
|
29
|
+
print("ALTERNATIVE: For direct Meta authentication, set META_APP_ID to your Meta App ID.")
|
|
28
30
|
if not META_APP_SECRET:
|
|
29
|
-
print("WARNING: META_APP_SECRET environment variable is not set.
|
|
31
|
+
print("WARNING: META_APP_SECRET environment variable is not set.")
|
|
32
|
+
print("NOTE: This is only needed for direct Meta authentication. Pipeboard authentication doesn't require this.")
|
|
33
|
+
print("RECOMMENDED: Use Pipeboard authentication by setting PIPEBOARD_API_TOKEN instead.")
|
|
30
34
|
|
|
31
35
|
# Configure logging to file
|
|
32
36
|
def setup_logging():
|
|
@@ -4,10 +4,10 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "meta-ads-mcp"
|
|
7
|
-
version = "0.3.
|
|
7
|
+
version = "0.3.7"
|
|
8
8
|
description = "Model Calling Protocol (MCP) plugin for interacting with Meta Ads API"
|
|
9
9
|
readme = "README.md"
|
|
10
|
-
requires-python = ">=3.
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
11
|
authors = [
|
|
12
12
|
{name = "Yves Junqueira", email = "yves.junqueira@gmail.com"},
|
|
13
13
|
]
|
meta_ads_mcp-0.3.5/brands/injurypayouts.com/120221013820800183_76c8b7fd0c627bce0d6ad833682f45e5.jpg
DELETED
|
Binary file
|
meta_ads_mcp-0.3.5/brands/injurypayouts.com/120221013841190183_cc1ff1ad28a037f397fd0e1636e8239a.jpg
DELETED
|
Binary file
|
meta_ads_mcp-0.3.5/brands/injurypayouts.com/120221013863110183_76f042047ce288bfbf9e103ffa10c50f.jpg
DELETED
|
Binary file
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|