meta-ads-mcp-python 1.0.79__py3-none-any.whl

meta_ads_mcp/core/utils.py

@@ -0,0 +1,225 @@
+"""Utility functions for Meta Ads API."""
+
+import os
+import pathlib
+import platform
+import sys
+from typing import Any, Dict, List, Optional
+
+import httpx
+from loguru import logger
+from PIL import Image as PILImage  # noqa: F401  (re-exported for callers)
+
+# ---------------------------------------------------------------------------
+# Logging configuration (loguru)
+# ---------------------------------------------------------------------------
+# Remove the default stderr sink so we can control format and level precisely.
+logger.remove()
+
+_log_level = os.environ.get("LOG_LEVEL", "INFO").upper()
+
+# Console sink: WARNING+ only -- keeps stdio MCP transport clean.
+logger.add(sys.stderr, level="WARNING", format="{time} | {level} | {message}")
+
+
+def _log_file_path() -> pathlib.Path:
+    """Return a platform-appropriate log file path, creating the directory."""
+    if platform.system() == "Windows":
+        base = pathlib.Path(os.environ.get("APPDATA", str(pathlib.Path.home())))
+    elif platform.system() == "Darwin":
+        base = pathlib.Path.home() / "Library" / "Application Support"
+    else:
+        base = pathlib.Path.home() / ".config"
+    log_dir = base / "meta-ads-mcp"
+    log_dir.mkdir(parents=True, exist_ok=True)
+    return log_dir / "meta_ads_debug.log"
+
+
+# File sink: full detail for troubleshooting.
+logger.add(
+    _log_file_path(),
+    level=_log_level,
+    rotation="10 MB",
+    retention="7 days",
+    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {name}:{line} | {message}",
+)
+
+# ---------------------------------------------------------------------------
+# Convenience env-var constants (kept for backwards-compat with callers)
+# ---------------------------------------------------------------------------
+META_APP_ID: str = os.environ.get("META_APP_ID", "")
+META_APP_SECRET: str = os.environ.get("META_APP_SECRET", "")
+
+logger.info("meta-ads-mcp logging initialised (level={})", _log_level)
+logger.info("Platform: {} {}", platform.system(), platform.release())
+logger.info(
+    "Auth mode: {}",
+    "pipeboard" if os.environ.get("PIPEBOARD_API_TOKEN") else "direct-meta",
+)
+
+# ---------------------------------------------------------------------------
+# Global image store (used by resources.py)
+# ---------------------------------------------------------------------------
+ad_creative_images: Dict[str, Any] = {}
+
+
+# ---------------------------------------------------------------------------
+# Creative image URL extraction
+# ---------------------------------------------------------------------------
+
+
+def extract_creative_image_urls(creative: Dict[str, Any]) -> List[str]:
+    """Extract image URLs from a creative object, ordered by quality.
+
+    Args:
+        creative: Meta Ads creative object.
+
+    Returns:
+        Deduplicated list of image URLs, highest quality first.
+    """
+    image_urls: List[str] = []
+
+    # 1. image_urls_for_viewing (highest quality)
+    image_urls.extend(creative.get("image_urls_for_viewing") or [])
+
+    # 2. Direct image_url field
+    if creative.get("image_url"):
+        image_urls.append(creative["image_url"])
+
+    # 3. object_story_spec
+    story_spec = creative.get("object_story_spec", {})
+    link_data = story_spec.get("link_data", {})
+    for field in ("picture", "image_url"):
+        if link_data.get(field):
+            image_urls.append(link_data[field])
+    video_data = story_spec.get("video_data", {})
+    if video_data.get("image_url"):
+        image_urls.append(video_data["image_url"])
+
+    # 4. asset_feed_spec images
+    for img in (creative.get("asset_feed_spec") or {}).get("images", []):
+        if img.get("url"):
+            image_urls.append(img["url"])
+
+    # 5. thumbnail_url (lowest priority)
+    if creative.get("thumbnail_url"):
+        image_urls.append(creative["thumbnail_url"])
+
+    # Deduplicate, preserving order
+    seen: set = set()
+    unique: List[str] = []
+    for url in image_urls:
+        if url not in seen:
+            seen.add(url)
+            unique.append(url)
+    return unique
+
+
+# ---------------------------------------------------------------------------
+# Image download helpers
+# ---------------------------------------------------------------------------
+
+
+async def download_image(url: str) -> Optional[bytes]:
+    """Download an image from a URL.
+
+    Args:
+        url: Image URL.
+
+    Returns:
+        Raw image bytes, or None on failure.
+    """
+    headers = {"User-Agent": "curl/8.4.0", "Accept": "*/*"}
+    try:
+        async with httpx.AsyncClient(follow_redirects=True, timeout=30.0) as client:
+            response = await client.get(url, headers=headers)
+            if response.status_code == 200:
+                logger.debug("Downloaded {} bytes from {}", len(response.content), url)
+                return response.content
+            logger.warning("Image download failed: HTTP {} for {}", response.status_code, url)
+    except httpx.HTTPStatusError as exc:
+        logger.warning("HTTP error downloading {}: {}", url, exc)
+    except httpx.RequestError as exc:
+        logger.warning("Request error downloading {}: {}", url, exc)
+    except Exception:
+        logger.exception("Unexpected error downloading {}", url)
+    return None
+
+
+async def try_multiple_download_methods(url: str) -> Optional[bytes]:
+    """Try multiple strategies to download a Meta CDN image.
+
+    Args:
+        url: Image URL.
+
+    Returns:
+        Raw image bytes, or None if all methods fail.
+    """
+    # Method 1: direct curl-style request
+    data = await download_image(url)
+    if data:
+        return data
+
+    logger.debug("Direct download failed, trying browser UA for {}", url)
+
+    # Method 2: browser User-Agent
+    try:
+        headers = {
+            "User-Agent": (
+                "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
+                "AppleWebKit/537.36 (KHTML, like Gecko) "
+                "Chrome/91.0.4472.124 Safari/537.36"
+            ),
+            "Accept": "image/webp,image/apng,image/*,*/*;q=0.8",
+        }
+        async with httpx.AsyncClient(follow_redirects=True, timeout=30.0) as client:
+            response = await client.get(url, headers=headers)
+            response.raise_for_status()
+            logger.debug("Browser-UA download succeeded: {} bytes", len(response.content))
+            return response.content
+    except Exception as exc:
+        logger.debug("Browser-UA download failed for {}: {}", url, exc)
+
+    # Method 3: seed cookies via a Facebook visit first
+    try:
+        async with httpx.AsyncClient(follow_redirects=True, timeout=30.0) as client:
+            await client.get("https://www.facebook.com/", timeout=30.0)
+            response = await client.get(url, timeout=30.0)
+            response.raise_for_status()
+            logger.debug("Facebook-session download succeeded: {} bytes", len(response.content))
+            return response.content
+    except Exception as exc:
+        logger.debug("Facebook-session download failed for {}: {}", url, exc)
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Resource creation helper
+# ---------------------------------------------------------------------------
+
+
+def create_resource_from_image(
+    image_bytes: bytes, resource_id: str, name: str
+) -> Dict[str, Any]:
+    """Store image bytes and return a resource descriptor.
+
+    Args:
+        image_bytes: Raw image data.
+        resource_id: Unique identifier for the resource.
+        name: Human-readable name.
+
+    Returns:
+        Resource descriptor dict with uri and size.
+    """
+    ad_creative_images[resource_id] = {
+        "data": image_bytes,
+        "mime_type": "image/jpeg",
+        "name": name,
+    }
+    return {
+        "resource_id": resource_id,
+        "resource_uri": f"meta-ads://images/{resource_id}",
+        "name": name,
+        "size": len(image_bytes),
+    }

meta_ads_mcp/settings.py

@@ -0,0 +1,33 @@
+"""Configuration management for meta-ads-mcp."""
+
+from pydantic import Field
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    """Application settings loaded from environment variables."""
+
+    log_level: str = Field(default="INFO", description="Logging level")
+
+    # Meta direct-auth (optional -- Pipeboard auth takes precedence)
+    meta_app_id: str = Field(default="", description="Meta App ID for direct OAuth")
+    meta_app_secret: str = Field(default="", description="Meta App Secret for appsecret_proof signing")
+
+    # Pipeboard cloud auth (recommended)
+    pipeboard_api_token: str = Field(default="", description="Pipeboard API token for cloud-hosted auth")
+
+    # HTTP transport
+    server_host: str = Field(default="localhost", description="Host for streamable-http transport")
+    server_port: int = Field(default=8080, description="Port for streamable-http transport")
+
+
+def load_settings(**kwargs: object) -> Settings:
+    """Load application settings from environment variables.
+
+    Args:
+        **kwargs: Override any setting value.
+
+    Returns:
+        Populated Settings instance.
+    """
+    return Settings(**kwargs)

meta_ads_mcp_python-1.0.79.dist-info/METADATA

@@ -0,0 +1,187 @@
+Metadata-Version: 2.3
+Name: meta-ads-mcp-python
+Version: 1.0.79
+Summary: MCP server for Meta Ads API -- manage campaigns, ad sets, ads, and Business Manager accounts
+Keywords: meta,facebook,ads,api,mcp,claude
+Author: Yves Junqueira
+Author-email: Yves Junqueira <yves.junqueira@gmail.com>
+License: BUSL-1.1
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pydantic-settings>=2.10.1
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: python-dotenv>=1.1.0
+Requires-Dist: requests>=2.32.3
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: python-dateutil>=2.8.2
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/locomotive-agency/meta-ads-mcp-python
+Project-URL: Bug Tracker, https://github.com/locomotive-agency/meta-ads-mcp-python/issues
+Description-Content-Type: text/markdown
+
+# Meta Ads MCP
+
+A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for analysing Meta Ads campaigns through an AI interface. Retrieve performance data, visualize ad creatives, and surface insights for Facebook, Instagram, and other Meta platforms.
+
+> **Read-only:** All tools are strictly read-only. No tool creates, modifies, or deletes any data.
+
+> **Independent project:** This is an open-source project using Meta's public APIs. Not affiliated with or endorsed by Meta. For an officially approved Meta app, see [Pipeboard](https://pipeboard.co).
+
+---
+
+## Quick Start (Remote MCP)
+
+The fastest way to get started is the [Pipeboard remote MCP](https://pipeboard.co) — no local setup required.
+
+Remote MCP URL: `https://mcp.pipeboard.co/meta-ads-mcp`
+
+With token auth: `https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN`
+
+Get your token at [pipeboard.co/api-tokens](https://pipeboard.co/api-tokens).
+
+### Claude (Pro/Max)
+
+1. Go to [claude.ai/settings/integrations](https://claude.ai/settings/integrations)
+2. Click **Add Integration**, set the URL to `https://mcp.pipeboard.co/meta-ads-mcp`
+3. Click **Connect** and follow the prompts.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "meta-ads-remote": {
+      "url": "https://mcp.pipeboard.co/meta-ads-mcp?token=YOUR_PIPEBOARD_TOKEN"
+    }
+  }
+}
+```
+
+### Other MCP Clients
+
+Use the remote URL above. Full setup guides: [pipeboard.co](https://pipeboard.co)
+
+---
+
+## Local Installation
+
+> For advanced users. The remote MCP is recommended for most cases.
+
+**Requirements:** Python 3.12+, a Meta Developer App (App ID + Secret), and [uv](https://github.com/astral-sh/uv).
+
+```bash
+pip install meta-ads-mcp
+```
+
+### Authentication
+
+Copy `.env.example` to `.env` and set one of:
+
+```
+PIPEBOARD_API_TOKEN=your_token       # Recommended — no Meta app required
+META_APP_ID=your_app_id              # Direct Meta app credentials
+META_APP_SECRET=your_app_secret
+```
+
+### Run
+
+```bash
+meta-ads-mcp                         # stdio (default)
+python -m meta_ads_mcp --transport streamable-http --host localhost --port 8080  # HTTP
+```
+
+### Claude Desktop config
+
+```json
+{
+  "mcpServers": {
+    "meta-ads": {
+      "command": "meta-ads-mcp"
+    }
+  }
+}
+```
+
+---
+
+## Configuration
+
+| Variable | Description |
+|---|---|
+| `PIPEBOARD_API_TOKEN` | Pipeboard API token (recommended) |
+| `META_APP_ID` | Meta Developer App ID (direct auth) |
+| `META_APP_SECRET` | Meta Developer App Secret (direct auth) |
+| `LOG_LEVEL` | `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`) |
+| `SERVER_HOST` | HTTP transport host (default: `localhost`) |
+| `SERVER_PORT` | HTTP transport port (default: `8080`) |
+
+---
+
+## Available Tools
+
+| Tool | Description |
+|---|---|
+| `mcp_meta_ads_get_ad_accounts` | List accessible ad accounts |
+| `mcp_meta_ads_get_account_info` | Get details for a specific ad account |
+| `mcp_meta_ads_get_account_pages` | Get pages associated with an ad account |
+| `mcp_meta_ads_get_campaigns` | List campaigns with optional status filter |
+| `mcp_meta_ads_get_campaign_details` | Get details for a specific campaign |
+| `mcp_meta_ads_get_adsets` | List ad sets, optionally filtered by campaign |
+| `mcp_meta_ads_get_adset_details` | Get details for a specific ad set |
+| `mcp_meta_ads_get_ads` | List ads, optionally filtered by campaign or ad set |
+| `mcp_meta_ads_get_ad_details` | Get details for a specific ad |
+| `mcp_meta_ads_get_ad_creatives` | Get creative details (text, images, URLs) |
+| `mcp_meta_ads_get_ad_image` | Download and visualize an ad image |
+| `mcp_meta_ads_get_insights` | Get performance metrics with attribution windows and breakdowns |
+| `mcp_meta_ads_get_login_link` | Get a login link for Meta authentication |
+| `mcp_meta_ads_search_interests` | Search interest targeting options by keyword |
+| `mcp_meta_ads_get_interest_suggestions` | Get interest suggestions based on existing interests |
+| `mcp_meta_ads_validate_interests` | Validate interest names or IDs |
+| `mcp_meta_ads_search_behaviors` | List available behavior targeting options |
+| `mcp_meta_ads_search_demographics` | List demographic targeting options |
+| `mcp_meta_ads_search_geo_locations` | Search geographic targeting locations |
+| `mcp_meta_ads_search` | Generic search across accounts, campaigns, ads, and pages |
+| `mcp_meta_ads_get_businesses` | List all Business Manager accounts |
+| `mcp_meta_ads_get_business_ad_accounts` | List ad accounts under a Business Manager |
+| `mcp_meta_ads_find_client_account` | Search for a client account across Business Managers |
+| `mcp_meta_ads_get_business_details` | Get details for a specific Business Manager |
+
+---
+
+## Troubleshooting
+
+- **Auth errors:** Check your token/credentials in `.env`. Use `mcp_meta_ads_get_login_link` to re-authenticate.
+- **No accounts returned:** Ensure the user has access to at least one ad account in Meta Business Manager.
+- **Tool not found:** Confirm the server is running and your client config is correct.
+
+---
+
+## Privacy and Security
+
+- Remote MCP: auth is handled in the cloud, no tokens stored locally.
+- Local install: tokens are cached on your machine. Never commit your `.env` file.
+- The server never exposes your access token to the LLM.
+
+---
+
+## Licensing
+
+Licensed under the [Business Source License 1.1](LICENSE). Free for individual and business use. Converts to Apache 2.0 on January 1, 2029. You may not offer this as a competing hosted service.
+
+For commercial licensing: [info@pipeboard.co](mailto:info@pipeboard.co)
+
+---
+
+## Support
+
+- [Discord](https://discord.gg/YzMwQ8zrjr)
+- [GitHub Issues](https://github.com/pipeboard-co/meta-ads-mcp/issues)
+- [Email](mailto:info@pipeboard.co)

meta_ads_mcp_python-1.0.79.dist-info/RECORD

@@ -0,0 +1,29 @@
+meta_ads_mcp/__init__.py,sha256=-thYt7S219dpbxUk4NFJOxAjP3M2TgDv0ZTt_ygh48U,1759
+meta_ads_mcp/__main__.py,sha256=XaQt3iXftG_7f0Zu7Wop9SeFgrD2WBn0EQOaPMc27d8,207
+meta_ads_mcp/core/__init__.py,sha256=QBtXQtHlni_kg0DzsJk2w9yjMRQ481Wm_DEmtTMtxec,1982
+meta_ads_mcp/core/accounts.py,sha256=Qfcp2p0EUqqUqFPzRnQMPKkblQL97Ka66vN5vEeXceo,5815
+meta_ads_mcp/core/ads.py,sha256=SlqOaUDEAEKyV-h-Whze7v6HRZm4uRcL-3j6_EIyTCk,124995
+meta_ads_mcp/core/ads_library.py,sha256=smGz9FhM6RIUjlQT4Jv1BaZmXahGdK21eRCB7QMhK-4,3228
+meta_ads_mcp/core/adsets.py,sha256=og2WVmPyXO7c9PtrX8g21PfpcksmwAVZcOGzlqD-FZ0,37429
+meta_ads_mcp/core/api.py,sha256=60DLCo3YsuqlbpI76q6qdW-jiVrFn3DsWdUPbeI9iMg,21645
+meta_ads_mcp/core/auth.py,sha256=saZZyYE0nLgoUFVsIfTcAWq4XZN5orI0DCI5xmxGtbQ,23649
+meta_ads_mcp/core/authentication.py,sha256=dQ-vFrTuP-uzkfOuAJf4d4RketOUnCZeF891LkHQcDg,10472
+meta_ads_mcp/core/budget_schedules.py,sha256=ljTloal8ohFJTOSqaZhbRnvA6SRW0z5RvvFTkfVtxTk,2892
+meta_ads_mcp/core/callback_server.py,sha256=fpDl9JEMpvbfmHBPj2R5T55JjeGEL9bbAjeWhOUAQcg,9354
+meta_ads_mcp/core/campaigns.py,sha256=JAAOPbnxMWhwtNsOhqX9QmXWt8pSDX0MqJ1Ih9SeNTM,17162
+meta_ads_mcp/core/duplication.py,sha256=fLZsJrSlvnLjdMLCww_nA1CiaYivbGLPxVcJbepzlzQ,22974
+meta_ads_mcp/core/http_auth_integration.py,sha256=lGpKhfzJcyWugBcYEvypY-qnlt-3UDBLqh7xAUH0DGw,12473
+meta_ads_mcp/core/insights.py,sha256=T0Qwsfd9QUiJOf8gAvhtp_zs5OCLmOhSbBpIHqyKQPo,9114
+meta_ads_mcp/core/mcc.py,sha256=XozUBRGzh6V4YLEJjNQcam71GzgSR8L-WKAU9a6q3s4,8010
+meta_ads_mcp/core/openai_deep_research.py,sha256=EdYSZAHK0llS6YthXSXWrU3cJn5F_pVeimIWD9M_LiY,19069
+meta_ads_mcp/core/pipeboard_auth.py,sha256=06PHiSg1rUBRY4FJ-eo-EFi9cVe32hwhjDkxXHykPKY,24524
+meta_ads_mcp/core/reports.py,sha256=4_6MgwkdXiGedh3cGVgFaCsiHrcaO9hiAl3-gAgCkgw,5813
+meta_ads_mcp/core/resources.py,sha256=-zIIfZulpo76vcKv6jhAlQq91cR2SZ3cjYZt3ek3x0w,1236
+meta_ads_mcp/core/server.py,sha256=jSUkOzwxIL7v8eIvuN9weBoq8R7s5GRSrec-AGFoFDY,17892
+meta_ads_mcp/core/targeting.py,sha256=S5m3zVs4rnuwC4eIt0hLsTf7_mATUnsXYNTCXJkAXz0,25274
+meta_ads_mcp/core/utils.py,sha256=dQJURUXyB_ojWk9NlftjanR48-cElA3iOT35XMTF01c,7832
+meta_ads_mcp/settings.py,sha256=F-uPfXrnDFyW7cJ5NmWhg1PYmexyVHCCrwU2LXUDlo4,1171
+meta_ads_mcp_python-1.0.79.dist-info/WHEEL,sha256=WvwXFgRajeoYkfRVmDhkP4Qlqo31Mk687zIO2QQoFmw,80
+meta_ads_mcp_python-1.0.79.dist-info/entry_points.txt,sha256=1Jl6H25XiykQqFHYOYJQ4LJrrMd4o_Fn0ombZaHHP_g,64
+meta_ads_mcp_python-1.0.79.dist-info/METADATA,sha256=H13RNdBQWRxonE5wnXMSjMCXmvh6O0hgNng1leZKxuE,6775
+meta_ads_mcp_python-1.0.79.dist-info/RECORD,,

meta_ads_mcp_python-1.0.79.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.7
+Root-Is-Purelib: true
+Tag: py3-none-any

meta_ads_mcp_python-1.0.79.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+meta-ads-mcp = meta_ads_mcp.core.server:main
+