meta-ads-mcp-python 1.0.79__tar.gz

meta_ads_mcp_python-1.0.79/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,160 @@
+# 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/pyproject.toml

@@ -0,0 +1,84 @@
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "meta-ads-mcp-python"
+version = "1.0.79"
+description = "MCP server for Meta Ads API -- manage campaigns, ad sets, ads, and Business Manager accounts"
+authors = [{ name = "Yves Junqueira", email = "yves.junqueira@gmail.com" }]
+license = { text = "BUSL-1.1" }
+readme = "README.md"
+keywords = ["meta", "facebook", "ads", "api", "mcp", "claude"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: Other/Proprietary License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+]
+requires-python = ">= 3.12"
+dependencies = [
+    "fastmcp>=2.0.0",
+    "loguru>=0.7.3",
+    "pydantic>=2.11.7",
+    "pydantic-settings>=2.10.1",
+    "httpx>=0.26.0",
+    "python-dotenv>=1.1.0",
+    "requests>=2.32.3",
+    "Pillow>=10.0.0",
+    "python-dateutil>=2.8.2",
+]
+
+[dependency-groups]
+dev = [
+    "mypy>=1.15.0",
+    "pre-commit>=4.1.0",
+    "pytest>=8.3.4",
+    "pytest-asyncio>=0.25.3",
+    "ruff>=0.9.7",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/locomotive-agency/meta-ads-mcp-python"
+"Bug Tracker" = "https://github.com/locomotive-agency/meta-ads-mcp-python/issues"
+
+[project.scripts]
+meta-ads-mcp = "meta_ads_mcp.core.server:main"
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+markers = [
+    "e2e: marks tests as end-to-end (requires running MCP server) - excluded from default runs",
+]
+addopts = "-v --strict-markers -m 'not e2e'"
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[tool.ruff]
+line-length = 88
+src = ["src"]
+output-format = "concise"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "C90", "B", "N", "D", "ANN", "TRY", "PD", "RUF200", "UP", "G"]
+ignore = ["E501", "ANN003"]
+
+[tool.ruff.lint.extend-per-file-ignores]
+"__init__.py" = ["F401", "F403", "E402"]
+"tests/**/*.py" = ["D", "ANN"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.lint.mccabe]
+max-complexity = 6
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = true
+
+[tool.uv.build-backend]
+module-name = "meta_ads_mcp"

meta_ads_mcp_python-1.0.79/src/meta_ads_mcp/__init__.py

@@ -0,0 +1,79 @@
+"""
+Meta Ads MCP - Python Package
+
+This package provides a Meta Ads MCP integration
+"""
+
+from meta_ads_mcp.core.server import main
+
+__version__ = "1.0.79"
+
+__all__ = [
+    'get_ad_accounts',
+    'get_account_info',
+    'get_campaigns',
+    'get_campaign_details',
+    'create_campaign',
+    'get_adsets',
+    'get_adset_details',
+    'update_adset',
+    'get_ads',
+    'get_ad_details',
+    'get_ad_creatives',
+    'get_ad_image',
+    'update_ad',
+    'get_insights',
+    # 'get_login_link' is conditionally exported via core.__all__
+    'login_cli',
+    'main',
+    'search_interests',
+    'get_interest_suggestions',
+    'estimate_audience_size',
+    'search_behaviors',
+    'search_demographics',
+    'search_geo_locations',
+    # MCC / Business Manager tools
+    'get_businesses',
+    'get_business_ad_accounts',
+    'find_client_account',
+    'get_business_details',
+]
+
+# Import key functions to make them available at package level
+from .core import (
+    get_ad_accounts,
+    get_account_info,
+    get_campaigns,
+    get_campaign_details,
+    create_campaign,
+    get_adsets,
+    get_adset_details,
+    update_adset,
+    get_ads,
+    get_ad_details,
+    get_ad_creatives,
+    get_ad_image,
+    update_ad,
+    get_insights,
+    login_cli,
+    main,
+    search_interests,
+    get_interest_suggestions,
+    estimate_audience_size,
+    search_behaviors,
+    search_demographics,
+    search_geo_locations,
+    # MCC / Business Manager tools
+    get_businesses,
+    get_business_ad_accounts,
+    find_client_account,
+    get_business_details,
+)
+
+# Define a main function to be used as a package entry point
+def entrypoint():
+    """Main entry point for the package when invoked with uvx."""
+    return main() 
+
+# Re-export main for direct access
+main = main 

meta_ads_mcp_python-1.0.79/src/meta_ads_mcp/__main__.py

@@ -0,0 +1,10 @@
+"""
+Meta Ads MCP - Main Entry Point
+
+This module allows the package to be executed directly via `python -m meta_ads_mcp`
+"""
+
+from meta_ads_mcp.core.server import main
+
+if __name__ == "__main__":
+    main() 

meta_ads_mcp_python-1.0.79/src/meta_ads_mcp/core/__init__.py

@@ -0,0 +1,55 @@
+"""Core functionality for Meta Ads API MCP package."""
+
+from .server import mcp_server
+from .accounts import get_ad_accounts, get_account_info
+from .campaigns import get_campaigns, get_campaign_details
+from .adsets import get_adsets, get_adset_details
+from .ads import get_ads, get_ad_details, get_creative_details, get_ad_creatives, get_ad_image
+from .insights import get_insights
+from . import authentication  # Import module to register conditional auth tools
+from .server import login_cli, main
+from .auth import login
+from . import ads_library  # Import module to register conditional tools
+from .targeting import search_interests, get_interest_suggestions, estimate_audience_size, search_behaviors, search_demographics, search_geo_locations
+from . import reports  # Import module to register conditional tools
+from . import duplication  # Import module to register conditional duplication tools
+from .openai_deep_research import search, fetch  # OpenAI MCP Deep Research tools
+from .mcc import (  # Business Manager (MCC) tools
+    get_businesses,
+    get_business_ad_accounts,
+    find_client_account,
+    get_business_details,
+)
+
+__all__ = [
+    'mcp_server',
+    'get_ad_accounts',
+    'get_account_info',
+    'get_campaigns',
+    'get_campaign_details',
+    'get_adsets',
+    'get_adset_details',
+    'get_ads',
+    'get_ad_details',
+    'get_creative_details',
+    'get_ad_creatives',
+    'get_ad_image',
+    'get_insights',
+    # Note: 'get_login_link' is registered conditionally by the authentication module
+    'login_cli',
+    'login',
+    'main',
+    'search_interests',
+    'get_interest_suggestions',
+    'estimate_audience_size',
+    'search_behaviors',
+    'search_demographics',
+    'search_geo_locations',
+    'search',  # OpenAI MCP Deep Research search tool
+    'fetch',   # OpenAI MCP Deep Research fetch tool
+    # MCC / Business Manager tools
+    'get_businesses',
+    'get_business_ad_accounts',
+    'find_client_account',
+    'get_business_details',
+]