meta-ads-mcp 0.3.1__py3-none-any.whl → 0.3.2__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 +1 -1
- meta_ads_mcp/api.py +55 -1
- meta_ads_mcp/core/adsets.py +1 -1
- meta_ads_mcp/core/api.py +1 -1
- meta_ads_mcp/core/auth.py +13 -2
- meta_ads_mcp/core/authentication.py +1 -1
- meta_ads_mcp/core/callback_server.py +55 -1
- {meta_ads_mcp-0.3.1.dist-info → meta_ads_mcp-0.3.2.dist-info}/METADATA +43 -113
- {meta_ads_mcp-0.3.1.dist-info → meta_ads_mcp-0.3.2.dist-info}/RECORD +12 -12
- {meta_ads_mcp-0.3.1.dist-info → meta_ads_mcp-0.3.2.dist-info}/WHEEL +0 -0
- {meta_ads_mcp-0.3.1.dist-info → meta_ads_mcp-0.3.2.dist-info}/entry_points.txt +0 -0
- {meta_ads_mcp-0.3.1.dist-info → meta_ads_mcp-0.3.2.dist-info}/licenses/LICENSE +0 -0
meta_ads_mcp/__init__.py
CHANGED
meta_ads_mcp/api.py
CHANGED
|
@@ -48,6 +48,13 @@ callback_server_port = None
|
|
|
48
48
|
# Global token container for communication between threads
|
|
49
49
|
token_container = {"token": None, "expires_in": None, "user_id": None}
|
|
50
50
|
|
|
51
|
+
# Add these at the top of the file with the other global variables
|
|
52
|
+
callback_server_instance = None
|
|
53
|
+
server_shutdown_timer = None
|
|
54
|
+
|
|
55
|
+
# Add this near other constants in the file
|
|
56
|
+
CALLBACK_SERVER_TIMEOUT = 180 # 3 minutes timeout
|
|
57
|
+
|
|
51
58
|
# Configuration class to store app ID and other config
|
|
52
59
|
class MetaConfig:
|
|
53
60
|
_instance = None
|
|
@@ -1875,13 +1882,50 @@ async def try_multiple_download_methods(url: str) -> Optional[bytes]:
|
|
|
1875
1882
|
|
|
1876
1883
|
return None
|
|
1877
1884
|
|
|
1885
|
+
def shutdown_callback_server():
|
|
1886
|
+
"""Shutdown the callback server if it's running"""
|
|
1887
|
+
global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
|
|
1888
|
+
|
|
1889
|
+
with callback_server_lock:
|
|
1890
|
+
if not callback_server_running:
|
|
1891
|
+
print("Callback server is not running")
|
|
1892
|
+
return
|
|
1893
|
+
|
|
1894
|
+
if server_shutdown_timer is not None:
|
|
1895
|
+
server_shutdown_timer.cancel()
|
|
1896
|
+
server_shutdown_timer = None
|
|
1897
|
+
|
|
1898
|
+
print(f"Shutting down callback server on port {callback_server_port}")
|
|
1899
|
+
|
|
1900
|
+
# Shutdown the server if it exists
|
|
1901
|
+
if callback_server_instance:
|
|
1902
|
+
try:
|
|
1903
|
+
callback_server_instance.shutdown()
|
|
1904
|
+
callback_server_instance = None
|
|
1905
|
+
callback_server_running = False
|
|
1906
|
+
print("Callback server has been shut down")
|
|
1907
|
+
except Exception as e:
|
|
1908
|
+
print(f"Error shutting down callback server: {e}")
|
|
1909
|
+
else:
|
|
1910
|
+
print("No server instance to shut down")
|
|
1911
|
+
|
|
1878
1912
|
def start_callback_server():
|
|
1879
1913
|
"""Start the callback server if it's not already running"""
|
|
1880
|
-
global callback_server_thread, callback_server_running, callback_server_port
|
|
1914
|
+
global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
|
|
1881
1915
|
|
|
1882
1916
|
with callback_server_lock:
|
|
1883
1917
|
if callback_server_running:
|
|
1884
1918
|
print(f"Callback server already running on port {callback_server_port}")
|
|
1919
|
+
|
|
1920
|
+
# Reset the shutdown timer if one exists
|
|
1921
|
+
if server_shutdown_timer is not None:
|
|
1922
|
+
server_shutdown_timer.cancel()
|
|
1923
|
+
|
|
1924
|
+
server_shutdown_timer = threading.Timer(CALLBACK_SERVER_TIMEOUT, shutdown_callback_server)
|
|
1925
|
+
server_shutdown_timer.daemon = True
|
|
1926
|
+
server_shutdown_timer.start()
|
|
1927
|
+
print(f"Reset server shutdown timer to {CALLBACK_SERVER_TIMEOUT} seconds")
|
|
1928
|
+
|
|
1885
1929
|
return callback_server_port
|
|
1886
1930
|
|
|
1887
1931
|
# Find an available port
|
|
@@ -1913,6 +1957,7 @@ def start_callback_server():
|
|
|
1913
1957
|
|
|
1914
1958
|
# Create and start server in a daemon thread
|
|
1915
1959
|
server = HTTPServer(('localhost', port), handler_class)
|
|
1960
|
+
callback_server_instance = server
|
|
1916
1961
|
print(f"Callback server starting on port {port}")
|
|
1917
1962
|
|
|
1918
1963
|
# Create a simple flag to signal when the server is ready
|
|
@@ -1942,6 +1987,15 @@ def start_callback_server():
|
|
|
1942
1987
|
|
|
1943
1988
|
callback_server_running = True
|
|
1944
1989
|
|
|
1990
|
+
# Set a timer to shutdown the server after CALLBACK_SERVER_TIMEOUT seconds
|
|
1991
|
+
if server_shutdown_timer is not None:
|
|
1992
|
+
server_shutdown_timer.cancel()
|
|
1993
|
+
|
|
1994
|
+
server_shutdown_timer = threading.Timer(CALLBACK_SERVER_TIMEOUT, shutdown_callback_server)
|
|
1995
|
+
server_shutdown_timer.daemon = True
|
|
1996
|
+
server_shutdown_timer.start()
|
|
1997
|
+
print(f"Server will automatically shut down after {CALLBACK_SERVER_TIMEOUT} seconds of inactivity")
|
|
1998
|
+
|
|
1945
1999
|
# Verify the server is actually accepting connections
|
|
1946
2000
|
try:
|
|
1947
2001
|
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
|
meta_ads_mcp/core/adsets.py
CHANGED
|
@@ -6,7 +6,7 @@ from .api import meta_api_tool, make_api_request
|
|
|
6
6
|
from .accounts import get_ad_accounts
|
|
7
7
|
from .server import mcp_server
|
|
8
8
|
import asyncio
|
|
9
|
-
from .callback_server import start_callback_server, update_confirmation
|
|
9
|
+
from .callback_server import start_callback_server, shutdown_callback_server, update_confirmation
|
|
10
10
|
import urllib.parse
|
|
11
11
|
|
|
12
12
|
|
meta_ads_mcp/core/api.py
CHANGED
|
@@ -6,7 +6,7 @@ import httpx
|
|
|
6
6
|
import asyncio
|
|
7
7
|
import functools
|
|
8
8
|
import os
|
|
9
|
-
from .auth import needs_authentication, get_current_access_token, auth_manager, start_callback_server
|
|
9
|
+
from .auth import needs_authentication, get_current_access_token, auth_manager, start_callback_server, shutdown_callback_server
|
|
10
10
|
from .utils import logger
|
|
11
11
|
|
|
12
12
|
# Constants
|
meta_ads_mcp/core/auth.py
CHANGED
|
@@ -13,9 +13,10 @@ import requests
|
|
|
13
13
|
|
|
14
14
|
# Import from the new callback server module
|
|
15
15
|
from .callback_server import (
|
|
16
|
-
start_callback_server,
|
|
16
|
+
start_callback_server,
|
|
17
|
+
shutdown_callback_server,
|
|
17
18
|
token_container,
|
|
18
|
-
|
|
19
|
+
callback_server_port
|
|
19
20
|
)
|
|
20
21
|
|
|
21
22
|
# Import the new Pipeboard authentication
|
|
@@ -398,6 +399,16 @@ def exchange_token_for_long_lived(short_lived_token):
|
|
|
398
399
|
|
|
399
400
|
async def get_current_access_token() -> Optional[str]:
|
|
400
401
|
"""Get the current access token from auth manager"""
|
|
402
|
+
# Check for environment variable first - this takes highest precedence
|
|
403
|
+
env_token = os.environ.get("META_ACCESS_TOKEN")
|
|
404
|
+
if env_token:
|
|
405
|
+
logger.debug("Using access token from META_ACCESS_TOKEN environment variable")
|
|
406
|
+
# Basic validation
|
|
407
|
+
if len(env_token) < 20: # Most Meta tokens are much longer
|
|
408
|
+
logger.error(f"TOKEN VALIDATION FAILED: Token from environment variable appears malformed (length: {len(env_token)})")
|
|
409
|
+
return None
|
|
410
|
+
return env_token
|
|
411
|
+
|
|
401
412
|
# Use the singleton auth manager
|
|
402
413
|
global auth_manager
|
|
403
414
|
|
|
@@ -4,7 +4,7 @@ import json
|
|
|
4
4
|
import asyncio
|
|
5
5
|
import os
|
|
6
6
|
from .api import meta_api_tool
|
|
7
|
-
from .auth import start_callback_server, auth_manager, get_current_access_token
|
|
7
|
+
from .auth import start_callback_server, shutdown_callback_server, auth_manager, get_current_access_token
|
|
8
8
|
from .server import mcp_server
|
|
9
9
|
from .utils import logger, META_APP_SECRET
|
|
10
10
|
from .pipeboard_auth import pipeboard_auth_manager
|
|
@@ -24,6 +24,11 @@ callback_server_thread = None
|
|
|
24
24
|
callback_server_lock = threading.Lock()
|
|
25
25
|
callback_server_running = False
|
|
26
26
|
callback_server_port = None
|
|
27
|
+
callback_server_instance = None
|
|
28
|
+
server_shutdown_timer = None
|
|
29
|
+
|
|
30
|
+
# Timeout in seconds before shutting down the callback server
|
|
31
|
+
CALLBACK_SERVER_TIMEOUT = 180 # 3 minutes timeout
|
|
27
32
|
|
|
28
33
|
|
|
29
34
|
class CallbackHandler(BaseHTTPRequestHandler):
|
|
@@ -877,6 +882,35 @@ class CallbackHandler(BaseHTTPRequestHandler):
|
|
|
877
882
|
return
|
|
878
883
|
|
|
879
884
|
|
|
885
|
+
def shutdown_callback_server():
|
|
886
|
+
"""
|
|
887
|
+
Shutdown the callback server if it's running
|
|
888
|
+
"""
|
|
889
|
+
global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
|
|
890
|
+
|
|
891
|
+
with callback_server_lock:
|
|
892
|
+
if not callback_server_running:
|
|
893
|
+
print("Callback server is not running")
|
|
894
|
+
return
|
|
895
|
+
|
|
896
|
+
if server_shutdown_timer is not None:
|
|
897
|
+
server_shutdown_timer.cancel()
|
|
898
|
+
server_shutdown_timer = None
|
|
899
|
+
|
|
900
|
+
print(f"Shutting down callback server on port {callback_server_port}")
|
|
901
|
+
|
|
902
|
+
# Shutdown the server if it exists
|
|
903
|
+
if callback_server_instance:
|
|
904
|
+
try:
|
|
905
|
+
callback_server_instance.shutdown()
|
|
906
|
+
callback_server_instance = None
|
|
907
|
+
callback_server_running = False
|
|
908
|
+
print("Callback server has been shut down")
|
|
909
|
+
except Exception as e:
|
|
910
|
+
print(f"Error shutting down callback server: {e}")
|
|
911
|
+
else:
|
|
912
|
+
print("No server instance to shut down")
|
|
913
|
+
|
|
880
914
|
def start_callback_server() -> int:
|
|
881
915
|
"""
|
|
882
916
|
Start the callback server if it's not already running
|
|
@@ -884,11 +918,21 @@ def start_callback_server() -> int:
|
|
|
884
918
|
Returns:
|
|
885
919
|
Port number the server is running on
|
|
886
920
|
"""
|
|
887
|
-
global callback_server_thread, callback_server_running, callback_server_port
|
|
921
|
+
global callback_server_thread, callback_server_running, callback_server_port, callback_server_instance, server_shutdown_timer
|
|
888
922
|
|
|
889
923
|
with callback_server_lock:
|
|
890
924
|
if callback_server_running:
|
|
891
925
|
print(f"Callback server already running on port {callback_server_port}")
|
|
926
|
+
|
|
927
|
+
# Reset the shutdown timer if one exists
|
|
928
|
+
if server_shutdown_timer is not None:
|
|
929
|
+
server_shutdown_timer.cancel()
|
|
930
|
+
|
|
931
|
+
server_shutdown_timer = threading.Timer(CALLBACK_SERVER_TIMEOUT, shutdown_callback_server)
|
|
932
|
+
server_shutdown_timer.daemon = True
|
|
933
|
+
server_shutdown_timer.start()
|
|
934
|
+
print(f"Reset server shutdown timer to {CALLBACK_SERVER_TIMEOUT} seconds")
|
|
935
|
+
|
|
892
936
|
return callback_server_port
|
|
893
937
|
|
|
894
938
|
# Find an available port
|
|
@@ -909,6 +953,7 @@ def start_callback_server() -> int:
|
|
|
909
953
|
try:
|
|
910
954
|
# Create and start server in a daemon thread
|
|
911
955
|
server = HTTPServer(('localhost', port), CallbackHandler)
|
|
956
|
+
callback_server_instance = server
|
|
912
957
|
print(f"Callback server starting on port {port}")
|
|
913
958
|
|
|
914
959
|
# Create a simple flag to signal when the server is ready
|
|
@@ -938,6 +983,15 @@ def start_callback_server() -> int:
|
|
|
938
983
|
|
|
939
984
|
callback_server_running = True
|
|
940
985
|
|
|
986
|
+
# Set a timer to shutdown the server after CALLBACK_SERVER_TIMEOUT seconds
|
|
987
|
+
if server_shutdown_timer is not None:
|
|
988
|
+
server_shutdown_timer.cancel()
|
|
989
|
+
|
|
990
|
+
server_shutdown_timer = threading.Timer(CALLBACK_SERVER_TIMEOUT, shutdown_callback_server)
|
|
991
|
+
server_shutdown_timer.daemon = True
|
|
992
|
+
server_shutdown_timer.start()
|
|
993
|
+
print(f"Server will automatically shut down after {CALLBACK_SERVER_TIMEOUT} seconds of inactivity")
|
|
994
|
+
|
|
941
995
|
# Verify the server is actually accepting connections
|
|
942
996
|
try:
|
|
943
997
|
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: meta-ads-mcp
|
|
3
|
-
Version: 0.3.
|
|
3
|
+
Version: 0.3.2
|
|
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
|
|
@@ -31,7 +31,7 @@ A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for in
|
|
|
31
31
|
<img width="380" height="200" src="https://glama.ai/mcp/servers/@pipeboard-co/meta-ads-mcp/badge" alt="Meta Ads MCP server" />
|
|
32
32
|
</a>
|
|
33
33
|
|
|
34
|
-
|
|
34
|
+
Screenshot: using an LLM to understand your ad performance.
|
|
35
35
|
|
|
36
36
|

|
|
37
37
|
|
|
@@ -55,11 +55,7 @@ Screenhot: using an LLM to understand your ad performance.
|
|
|
55
55
|
When using uv no specific installation is needed. We can use uvx to directly run meta-ads-mcp:
|
|
56
56
|
|
|
57
57
|
```bash
|
|
58
|
-
#
|
|
59
|
-
export PIPEBOARD_API_TOKEN=your_pipeboard_token # Get your token at https://pipeboard.co
|
|
60
|
-
uvx meta-ads-mcp
|
|
61
|
-
|
|
62
|
-
# Alternative: Use with direct Meta authentication
|
|
58
|
+
# Run with Meta authentication
|
|
63
59
|
uvx meta-ads-mcp --app-id YOUR_META_ADS_APP_ID
|
|
64
60
|
```
|
|
65
61
|
|
|
@@ -87,50 +83,26 @@ pip install meta-ads-mcp
|
|
|
87
83
|
After installation, you can run it as:
|
|
88
84
|
|
|
89
85
|
```bash
|
|
90
|
-
#
|
|
91
|
-
export PIPEBOARD_API_TOKEN=your_pipeboard_token # Get your token at https://pipeboard.co
|
|
92
|
-
python -m meta_ads_mcp
|
|
93
|
-
|
|
94
|
-
# Alternative: Use with direct Meta authentication
|
|
86
|
+
# Run with Meta authentication
|
|
95
87
|
python -m meta_ads_mcp --app-id YOUR_META_ADS_APP_ID
|
|
96
88
|
```
|
|
97
89
|
|
|
98
90
|
## Configuration
|
|
99
91
|
|
|
100
|
-
###
|
|
101
|
-
|
|
102
|
-
The easiest way to configure Meta Ads MCP is using Pipeboard authentication:
|
|
92
|
+
### Create a Meta Developer App (Required)
|
|
103
93
|
|
|
104
|
-
|
|
105
|
-
2. Set the environment variable:
|
|
106
|
-
```bash
|
|
107
|
-
export PIPEBOARD_API_TOKEN=your_pipeboard_token # Token obtainable via https://pipeboard.co
|
|
108
|
-
```
|
|
109
|
-
3. Run meta-ads-mcp without needing to set up a Meta Developer App:
|
|
110
|
-
```bash
|
|
111
|
-
uvx meta-ads-mcp
|
|
112
|
-
```
|
|
94
|
+
Before using the MCP server, you'll need to set up a Meta Developer App:
|
|
113
95
|
|
|
114
|
-
|
|
96
|
+
1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
|
|
97
|
+
2. Choose the "Consumer" app type
|
|
98
|
+
3. In your app settings, add the "Marketing API" product
|
|
99
|
+
4. Configure your app's OAuth redirect URI to include `http://localhost:8888/callback`
|
|
100
|
+
5. Note your App ID (Client ID) for use with the MCP
|
|
115
101
|
|
|
116
102
|
### Usage with Cursor or Claude Desktop
|
|
117
103
|
|
|
118
104
|
Add this to your `claude_desktop_config.json` to integrate with Claude or `~/.cursor/mcp.json` to integrate with Cursor:
|
|
119
105
|
|
|
120
|
-
```json
|
|
121
|
-
"mcpServers": {
|
|
122
|
-
"meta-ads": {
|
|
123
|
-
"command": "uvx",
|
|
124
|
-
"args": ["meta-ads-mcp"],
|
|
125
|
-
"env": {
|
|
126
|
-
"PIPEBOARD_API_TOKEN": "your_pipeboard_token" // Token obtainable via https://pipeboard.co
|
|
127
|
-
}
|
|
128
|
-
}
|
|
129
|
-
}
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
Or if you prefer direct Meta authentication (using your own Facebook app):
|
|
133
|
-
|
|
134
106
|
```json
|
|
135
107
|
"mcpServers": {
|
|
136
108
|
"meta-ads": {
|
|
@@ -274,54 +246,13 @@ Or if you prefer direct Meta authentication (using your own Facebook app):
|
|
|
274
246
|
|
|
275
247
|
16. `mcp_meta_ads_get_login_link`
|
|
276
248
|
- Get a clickable login link for Meta Ads authentication
|
|
277
|
-
- NOTE: This method should only be used if you're using your own Facebook app. If using Pipeboard authentication (recommended), set the PIPEBOARD_API_TOKEN environment variable instead (token obtainable via https://pipeboard.co).
|
|
278
249
|
- Inputs:
|
|
279
250
|
- `access_token` (optional): Meta API access token (will use cached token if not provided)
|
|
280
251
|
- Returns: A clickable resource link for Meta authentication
|
|
281
252
|
|
|
282
|
-
## Create a Meta Developer App
|
|
283
|
-
|
|
284
|
-
Before using the MCP server, you'll need to set up a Meta Developer App:
|
|
285
|
-
|
|
286
|
-
1. Go to [Meta for Developers](https://developers.facebook.com/) and create a new app
|
|
287
|
-
2. Choose the "Consumer" app type
|
|
288
|
-
3. In your app settings, add the "Marketing API" product
|
|
289
|
-
4. Configure your app's OAuth redirect URI to include `http://localhost:8888/callback`
|
|
290
|
-
5. Note your App ID (Client ID) for use with the MCP
|
|
291
|
-
|
|
292
253
|
## Authentication
|
|
293
254
|
|
|
294
|
-
The Meta Ads MCP
|
|
295
|
-
|
|
296
|
-
### 1. Pipeboard Authentication (Recommended ⭐)
|
|
297
|
-
|
|
298
|
-
This method uses [Pipeboard.co](https://pipeboard.co) to manage Meta API authentication, providing longer-lived tokens and a simplified flow:
|
|
299
|
-
|
|
300
|
-
1. **Get your Pipeboard token**: Sign up at [https://pipeboard.co](https://pipeboard.co) to generate your free API token
|
|
301
|
-
2. Set the `PIPEBOARD_API_TOKEN` environment variable with your token:
|
|
302
|
-
```bash
|
|
303
|
-
export PIPEBOARD_API_TOKEN=your_pipeboard_token
|
|
304
|
-
```
|
|
305
|
-
3. Run the Meta Ads MCP normally - it will automatically detect and use Pipeboard authentication:
|
|
306
|
-
```bash
|
|
307
|
-
uvx meta-ads-mcp
|
|
308
|
-
```
|
|
309
|
-
4. The first time you run a command, you'll be provided with a login URL to authorize with Meta
|
|
310
|
-
|
|
311
|
-
**Benefits of Pipeboard authentication:**
|
|
312
|
-
- ✅ Longer-lived tokens (60 days)
|
|
313
|
-
- ✅ No need to configure a Meta Developer App
|
|
314
|
-
- ✅ Simpler setup with just an API token
|
|
315
|
-
- ✅ Automatic token renewal
|
|
316
|
-
|
|
317
|
-
To test the Pipeboard authentication flow:
|
|
318
|
-
```bash
|
|
319
|
-
python test_pipeboard_auth.py --api-token YOUR_PIPEBOARD_TOKEN
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
### 2. Direct Meta OAuth (Legacy)
|
|
323
|
-
|
|
324
|
-
The traditional OAuth 2.0 flow designed for desktop apps. This method should only be used if you are using your own Facebook app instead of Pipeboard.
|
|
255
|
+
The Meta Ads MCP uses Meta's OAuth 2.0 authentication flow, designed for desktop apps:
|
|
325
256
|
|
|
326
257
|
When authenticating, it will:
|
|
327
258
|
|
|
@@ -330,7 +261,7 @@ When authenticating, it will:
|
|
|
330
261
|
3. Ask you to authorize the app
|
|
331
262
|
4. Redirect back to the local server to extract and store the token securely
|
|
332
263
|
|
|
333
|
-
This method requires you to [create a Meta Developer App](#create-a-meta-developer-app)
|
|
264
|
+
This method requires you to [create a Meta Developer App](#create-a-meta-developer-app) as described above.
|
|
334
265
|
|
|
335
266
|
## Troubleshooting and Logging
|
|
336
267
|
|
|
@@ -348,19 +279,11 @@ Log files are stored in a platform-specific location:
|
|
|
348
279
|
|
|
349
280
|
#### Authentication Issues
|
|
350
281
|
|
|
351
|
-
If you
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
|
|
355
|
-
|
|
356
|
-
- Verify your token in the Pipeboard dashboard
|
|
357
|
-
|
|
358
|
-
2. For App ID issues (when using direct authentication):
|
|
359
|
-
If you encounter errors like `(#200) Provide valid app ID`, check the following:
|
|
360
|
-
- Ensure you've set up a Meta Developer App correctly
|
|
361
|
-
- Verify that you're passing the correct App ID using one of these methods:
|
|
362
|
-
- Set the `META_APP_ID` environment variable: `export META_APP_ID=your_app_id`
|
|
363
|
-
- Pass it as a command-line argument: `meta-ads-mcp --app-id your_app_id`
|
|
282
|
+
If you encounter errors like `(#200) Provide valid app ID`, check the following:
|
|
283
|
+
- Ensure you've set up a Meta Developer App correctly
|
|
284
|
+
- Verify that you're passing the correct App ID using one of these methods:
|
|
285
|
+
- Set the `META_APP_ID` environment variable: `export META_APP_ID=your_app_id`
|
|
286
|
+
- Pass it as a command-line argument: `meta-ads-mcp --app-id your_app_id`
|
|
364
287
|
|
|
365
288
|
#### API Errors
|
|
366
289
|
|
|
@@ -399,15 +322,24 @@ uvx meta-ads-mcp --app-id=your_app_id
|
|
|
399
322
|
The Meta Ads MCP follows security best practices:
|
|
400
323
|
|
|
401
324
|
1. Tokens are cached in a platform-specific secure location:
|
|
402
|
-
- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
|
|
403
|
-
- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
|
|
404
|
-
- Linux: `~/.config/meta-ads-mcp/token_cache.json`
|
|
325
|
+
- Windows: `%APPDATA%\meta-ads-mcp\token_cache.json`
|
|
326
|
+
- macOS: `~/Library/Application Support/meta-ads-mcp/token_cache.json`
|
|
327
|
+
- Linux: `~/.config/meta-ads-mcp/token_cache.json`
|
|
405
328
|
|
|
406
329
|
2. You do not need to provide your access token for each command; it will be automatically retrieved from the cache.
|
|
407
330
|
|
|
408
|
-
3. You can set the
|
|
409
|
-
|
|
410
|
-
|
|
331
|
+
3. You can set the `META_APP_ID` environment variable instead of passing it as an argument:
|
|
332
|
+
```bash
|
|
333
|
+
export META_APP_ID=your_app_id
|
|
334
|
+
uvx meta-ads-mcp
|
|
335
|
+
```
|
|
336
|
+
|
|
337
|
+
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:
|
|
338
|
+
```bash
|
|
339
|
+
export META_ACCESS_TOKEN=your_access_token
|
|
340
|
+
uvx meta-ads-mcp
|
|
341
|
+
```
|
|
342
|
+
This is useful for CI/CD pipelines or when you already have a valid access token from another source.
|
|
411
343
|
|
|
412
344
|
## Testing
|
|
413
345
|
|
|
@@ -429,10 +361,9 @@ python test_meta_ads_auth.py --app-id YOUR_APP_ID --force-login
|
|
|
429
361
|
|
|
430
362
|
When using the Meta Ads MCP with an LLM interface (like Claude):
|
|
431
363
|
|
|
432
|
-
1.
|
|
433
|
-
2.
|
|
434
|
-
3.
|
|
435
|
-
4. Check specific account details with `mcp_meta_ads_get_account_info`
|
|
364
|
+
1. Test authentication by calling the `mcp_meta_ads_get_login_link` tool
|
|
365
|
+
2. Verify account access by calling `mcp_meta_ads_get_ad_accounts`
|
|
366
|
+
3. Check specific account details with `mcp_meta_ads_get_account_info`
|
|
436
367
|
|
|
437
368
|
These functions will automatically handle authentication if needed and provide a clickable login link if required.
|
|
438
369
|
|
|
@@ -443,20 +374,19 @@ These functions will automatically handle authentication if needed and provide a
|
|
|
443
374
|
If you encounter authentication issues:
|
|
444
375
|
|
|
445
376
|
1. When using the LLM interface:
|
|
446
|
-
-
|
|
447
|
-
- If using Pipeboard authentication (recommended), ensure the PIPEBOARD_API_TOKEN environment variable is set (token obtainable via https://pipeboard.co)
|
|
377
|
+
- Use the `mcp_meta_ads_get_login_link` tool to generate a fresh authentication link
|
|
448
378
|
- Ensure you click the link and complete the authorization flow in your browser
|
|
449
379
|
- Check that the callback server is running properly (the tool will report this)
|
|
450
380
|
|
|
451
|
-
2. When using
|
|
452
|
-
- Verify your `PIPEBOARD_API_TOKEN` is set correctly (token obtainable via https://pipeboard.co)
|
|
453
|
-
- Check if you need to complete the authorization process by visiting the provided login URL
|
|
454
|
-
- Try forcing a new login: `python test_pipeboard_auth.py --force-login`
|
|
455
|
-
|
|
456
|
-
3. When using direct Meta OAuth:
|
|
381
|
+
2. When using direct Meta OAuth:
|
|
457
382
|
- Run with `--force-login` to get a fresh token: `uvx meta-ads-mcp --login --app-id YOUR_APP_ID --force-login`
|
|
458
383
|
- Make sure the terminal has permissions to open a browser window
|
|
459
384
|
|
|
385
|
+
3. Skip authentication entirely by providing a token directly:
|
|
386
|
+
- If you already have a valid access token, you can bypass the authentication flow:
|
|
387
|
+
- `export META_ACCESS_TOKEN=your_access_token`
|
|
388
|
+
- This will ignore both the local token cache and the Pipeboard authentication
|
|
389
|
+
|
|
460
390
|
### API Errors
|
|
461
391
|
|
|
462
392
|
If you receive errors from the Meta API:
|
|
@@ -1,22 +1,22 @@
|
|
|
1
|
-
meta_ads_mcp/__init__.py,sha256=
|
|
1
|
+
meta_ads_mcp/__init__.py,sha256=Xa5R_8nWJqcRh6Jps90mcuihcp4bJDKGXGg1bwnoSz4,1236
|
|
2
2
|
meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
|
|
3
|
-
meta_ads_mcp/api.py,sha256=
|
|
3
|
+
meta_ads_mcp/api.py,sha256=z0pW1pV3hE75IeG9QTqB3K7QoQOUxUg2MBQ9IjAWUYA,84363
|
|
4
4
|
meta_ads_mcp/core/__init__.py,sha256=6T8iqrQrw9VHhKtncLqYWyDk8jeSBPs79hs1CSu-fLU,952
|
|
5
5
|
meta_ads_mcp/core/accounts.py,sha256=Nmp7lPxO9wmq25jWV7_H0LIqnEbBhpCVBlLGW2HUaq0,2277
|
|
6
6
|
meta_ads_mcp/core/ads.py,sha256=LMZOo6agi6tQl4JJPmrDUn-91n7DzfxG2TChmwcrWOY,12544
|
|
7
|
-
meta_ads_mcp/core/adsets.py,sha256=
|
|
8
|
-
meta_ads_mcp/core/api.py,sha256=
|
|
9
|
-
meta_ads_mcp/core/auth.py,sha256=
|
|
10
|
-
meta_ads_mcp/core/authentication.py,sha256=
|
|
11
|
-
meta_ads_mcp/core/callback_server.py,sha256=
|
|
7
|
+
meta_ads_mcp/core/adsets.py,sha256=WBPNaI7ITnUOnGMus4_0MX15DslOCzfM5q1zF1VWs2s,12408
|
|
8
|
+
meta_ads_mcp/core/api.py,sha256=9Whcs2orILhPiWkAR3qGmJNouYE5uri_e_Jzeh5Hjn8,14208
|
|
9
|
+
meta_ads_mcp/core/auth.py,sha256=pDARBh3NBNqCpxflVrVvR4VsWuIveFxQmb9-P-gLFDM,20730
|
|
10
|
+
meta_ads_mcp/core/authentication.py,sha256=2MG13r28OlIcOIgPSRrGXJ2-4JSt3ifU-oB9tiOsrKQ,6511
|
|
11
|
+
meta_ads_mcp/core/callback_server.py,sha256=AUymElaVwHqFyqB2wgqf6A68KsqwtKoYmY-7JZZt8Ks,43286
|
|
12
12
|
meta_ads_mcp/core/campaigns.py,sha256=20DHMwHppZuoZBg0owkf1BfmPBhWzkQcFgh5rQa-pAU,10480
|
|
13
13
|
meta_ads_mcp/core/insights.py,sha256=XAm4uu83gWp84PEGqAJ3GFIqlvg7prh6MdD71JfvBCo,18072
|
|
14
14
|
meta_ads_mcp/core/pipeboard_auth.py,sha256=VvbxEB8ZOhnMccLU7HI1HgaPWHCl5NGrzZCm-zzHze4,22798
|
|
15
15
|
meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
|
|
16
16
|
meta_ads_mcp/core/server.py,sha256=5WofyJZGzeDhbGzLXPhQjT0XnZwo0syeK8TM_XnJo4Q,5507
|
|
17
17
|
meta_ads_mcp/core/utils.py,sha256=EPmpBX3OZaTWRS_YuEk_PLLyLXj7DeR6Ks8WoaZ5JGQ,6366
|
|
18
|
-
meta_ads_mcp-0.3.
|
|
19
|
-
meta_ads_mcp-0.3.
|
|
20
|
-
meta_ads_mcp-0.3.
|
|
21
|
-
meta_ads_mcp-0.3.
|
|
22
|
-
meta_ads_mcp-0.3.
|
|
18
|
+
meta_ads_mcp-0.3.2.dist-info/METADATA,sha256=Q_05xZMow3h9ova-mvfiL210rWvy-Ix9B_sZEetjN4k,16212
|
|
19
|
+
meta_ads_mcp-0.3.2.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
|
|
20
|
+
meta_ads_mcp-0.3.2.dist-info/entry_points.txt,sha256=Dv2RkoBjRJBqj6CyhwqGIiwPCD-SCL1-7B9-zmVRuv0,57
|
|
21
|
+
meta_ads_mcp-0.3.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
|
|
22
|
+
meta_ads_mcp-0.3.2.dist-info/RECORD,,
|
|
File without changes
|
|
File without changes
|
|
File without changes
|