Skip to content
Back to search

facebook-ads-mcp-server

Facebook/Meta Ads MCP Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gomarble-ai--facebook-ads-mcp-server/badge.svg)](/listings/gomarble-ai--facebook-ads-mcp-server)

HTML

<a href="/listings/gomarble-ai--facebook-ads-mcp-server"><img src="/api/listings/gomarble-ai--facebook-ads-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

* Python 3.10+ * Dependencies listed in `requirements.txt`

1. **(Optional but Recommended) Create and Activate a Virtual Environment:** ```bash python3 -m venv venv source venv/bin/activate # On Windows use `venv\Scripts\activate` ```

Using a virtual environment helps manage project dependencies cleanly[[Source]](https://docs.python.org/3/tutorial/venv.html). 2. **Install Dependencies:** ```bash pip install -r requirements.txt ``` 3. **Obtain Meta Access Token:** Secure a Meta User Access Token with the necessary permissions (e.g., `ads_read`). You can generate this through the Meta Developer portal. Follow [this link](https://elfsight.com/blog/how-to-get-facebook-access-token/).

Usage with MCP Clients (e.g., Cursor, Claude Desktop)

To integrate this server with an MCP-compatible client, add a configuration([Claude](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server)) similar to the following. Replace `YOUR_META_ACCESS_TOKEN` with your actual token and adjust the path to `server.py` if necessary.

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": [
        "/path/to/your/fb-ads-mcp-server/server.py",
        "--fb-token",
        "YOUR_META_ACCESS_TOKEN"
      ]
      // If using a virtual environment, you might need to specify the python executable within the venv:
      // "command": "/path/to/your/fb-ads-mcp-server/venv/bin/python",
      // "args": [
      //   "/path/to/your/fb-ads-mcp-server/server.py",
      //   "--fb-token",
      //   "YOUR_META_ACCESS_TOKEN"
      // ]
    }
  }
}

Restart the MCP Client app after making the update in the configuration.

*(Note: On Windows, you might need to adjust the command structure or use `cmd /k` depending on your setup.)*

Debugging the Server

Execute `server.py`, providing the access token via the `--fb-token` argument.

python server.py --fb-token YOUR_META_ACCESS_TOKEN

Available MCP Tools

This MCP server provides tools for interacting with META Ads objects and data:

| Tool Name | Description | | ------------------------------- | -------------------------------------------------------- | | **Account & Object Read** | | | `list_ad_accounts` | Lists ad accounts linked to the token. | | `get_details_of_ad_account` | Retrieves details for a specific ad account. | | `get_campaign_by_id` | Retrieves details for a specific campaign. | | `get_adset_by_id` | Retrieves details for a specific ad set. | | `get_ad_by_id` | Retrieves details for a specific ad. | | `get_ad_creative_by_id` | Retrieves details for a specific ad creative. | | `get_adsets_by_ids` | Retrieves details for multiple ad sets by their IDs. | | **Fetching Collections** | | | `get_campaigns_by_adaccount` | Retrieves campaigns within an ad account. | | `get_adsets_by_adaccount` | Retrieves ad sets within an ad account. | | `get_ads_by_adaccount` | Retrieves ads within an ad account. | | `get_adsets_by_campaign` | Retrieves ad sets within a campaign. | | `get_ads_by_campaign` | Retrieves ads within a campaign. | | `get_ads_by_adset` | Retrieves ads within an ad set. | | `get_ad_creatives_by_ad_id` | Retrieves creatives associated with an ad. | | **Insights & Performance Data** | |

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

readme.md · README · 151 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Facebook/Meta Ads MCP Server
  2. [![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/gomarble-ai/facebook-ads-mcp-server)](https://archestra.ai/mcp-catalog/gomarble-ai__facebook-ads-mcp-server)
  3. [![smithery badge](https://smithery.ai/badge/@gomarble-ai/facebook-ads-mcp-server)](https://smithery.ai/server/@gomarble-ai/facebook-ads-mcp-server)
  4. This project provides an MCP server acting as an interface to the Meta Ads, enabling programmatic access to Meta Ads data and management features.
  5. <video controls width="1920" height="512" src="https://github.com/user-attachments/assets/c4a76dcf-cf5d-4a1d-b976-08165e880fe4">Your browser does not support the video tag.</video>
  6. ## Easy One-Click Setup
  7. For a simpler setup experience, we offer ready-to-use installers:
  8. 👉 **Download installer -** [https://gomarble.ai/mcp](https://gomarble.ai/mcp)
  9. ## Join our community for help and updates
  10. 👉 **Slack Community -** [AI in Ads](https://join.slack.com/t/ai-in-ads/shared_invite/zt-36hntbyf8-FSFixmwLb9mtEzVZhsToJQ)
  11. ## Try Google ads mcp server also
  12. 👉 **Google Ads MCP -** [Google Ads MCP](https://github.com/gomarble-ai/google-ads-mcp-server)
  13. ### What It Does
  14. - Installs and configures the MCP server locally
  15. - Automatically handles environment setup
  16. - Prompts for Meta token authentication during the process which is optional
  17. - If Meta access token is not provided then connect to GoMarble's server to create the token on your behalf
  18. ### Important Disclaimer
  19. This setup **does not require** you to manually obtain a Meta Developer Access Token.
  20. Instead, it connects securely to **GoMarble's server to create the token on your behalf**.
  21. GoMarble **does not store** your token — it is saved locally on your machine for use with the MCP server.
  22. ---
  23. ## Setup
  24. ### Prerequisites
  25. * Python 3.10+
  26. * Dependencies listed in `requirements.txt`
  27. 1. **(Optional but Recommended) Create and Activate a Virtual Environment:**
  28. ```bash
  29. python3 -m venv venv
  30. source venv/bin/activate # On Windows use `venv\Scripts\activate`
  31. ```
  32. Using a virtual environment helps manage project dependencies cleanly[[Source]](https://docs.python.org/3/tutorial/venv.html).
  33. 2. **Install Dependencies:**
  34. ```bash
  35. pip install -r requirements.txt
  36. ```
  37. 3. **Obtain Meta Access Token:** Secure a Meta User Access Token with the necessary permissions (e.g., `ads_read`). You can generate this through the Meta Developer portal. Follow [this link](https://elfsight.com/blog/how-to-get-facebook-access-token/).
  38. ### Usage with MCP Clients (e.g., Cursor, Claude Desktop)
  39. To integrate this server with an MCP-compatible client, add a configuration([Claude](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server)) similar to the following. Replace `YOUR_META_ACCESS_TOKEN` with your actual token and adjust the path to `server.py` if necessary.
  40. ```json
  41. {
  42. "mcpServers": {
  43. "fb-ads-mcp-server": {
  44. "command": "python",
  45. "args": [
  46. "/path/to/your/fb-ads-mcp-server/server.py",
  47. "--fb-token",
  48. "YOUR_META_ACCESS_TOKEN"
  49. ]
  50. // If using a virtual environment, you might need to specify the python executable within the venv:
  51. // "command": "/path/to/your/fb-ads-mcp-server/venv/bin/python",
  52. // "args": [
  53. // "/path/to/your/fb-ads-mcp-server/server.py",
  54. // "--fb-token",
  55. // "YOUR_META_ACCESS_TOKEN"
  56. // ]
  57. }
  58. }
  59. }
  60. ```
  61. Restart the MCP Client app after making the update in the configuration.
  62. *(Note: On Windows, you might need to adjust the command structure or use `cmd /k` depending on your setup.)*
  63. ### Debugging the Server
  64. Execute `server.py`, providing the access token via the `--fb-token` argument.
  65. ```bash
  66. python server.py --fb-token YOUR_META_ACCESS_TOKEN
  67. ```
  68. ### Available MCP Tools
  69. This MCP server provides tools for interacting with META Ads objects and data:
  70. | Tool Name | Description |
  71. | ------------------------------- | -------------------------------------------------------- |
  72. | **Account & Object Read** | |
  73. | `list_ad_accounts` | Lists ad accounts linked to the token. |
  74. | `get_details_of_ad_account` | Retrieves details for a specific ad account. |
  75. | `get_campaign_by_id` | Retrieves details for a specific campaign. |
  76. | `get_adset_by_id` | Retrieves details for a specific ad set. |
  77. | `get_ad_by_id` | Retrieves details for a specific ad. |
  78. | `get_ad_creative_by_id` | Retrieves details for a specific ad creative. |
  79. | `get_adsets_by_ids` | Retrieves details for multiple ad sets by their IDs. |
  80. | **Fetching Collections** | |
  81. | `get_campaigns_by_adaccount` | Retrieves campaigns within an ad account. |
  82. | `get_adsets_by_adaccount` | Retrieves ad sets within an ad account. |
  83. | `get_ads_by_adaccount` | Retrieves ads within an ad account. |
  84. | `get_adsets_by_campaign` | Retrieves ad sets within a campaign. |
  85. | `get_ads_by_campaign` | Retrieves ads within a campaign. |
  86. | `get_ads_by_adset` | Retrieves ads within an ad set. |
  87. | `get_ad_creatives_by_ad_id` | Retrieves creatives associated with an ad. |
  88. | **Insights & Performance Data** | |
  89. | `get_adaccount_insights` | Retrieves performance insights for an ad account. |
  90. | `get_campaign_insights` | Retrieves performance insights for a campaign. |
  91. | `get_adset_insights` | Retrieves performance insights for an ad set. |
  92. | `get_ad_insights` | Retrieves performance insights for an ad. |
  93. | `fetch_pagination_url` | Fetches data from a pagination URL (e.g., from insights).|
  94. | **Activity/Change History** | |
  95. | `get_activities_by_adaccount` | Retrieves change history for an ad account. |
  96. | `get_activities_by_adset` | Retrieves change history for an ad set. |
  97. *(Note: Most tools support additional parameters like `fields`, `filtering`, `limit`, pagination, date ranges, etc. Refer to the detailed docstrings within `server.py` for the full list and description of arguments for each tool.)*
  98. *(Note: If your Meta access token expires, you'll need to generate a new one and update the configuration file of the MCP Client with new token to continue using the tools.)*
  99. ### Dependencies
  100. * [mcp](https://pypi.org/project/mcp/) (>=1.6.0)
  101. * [requests](https://pypi.org/project/requests/) (>=2.32.3)
  102. ### License
  103. This project is licensed under the MIT License.
  104. ---
  105. ## Installing via Smithery
  106. To install Facebook Ads Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@gomarble-ai/facebook-ads-mcp-server):
  107. ```bash
  108. npx -y @smithery/cli install @gomarble-ai/facebook-ads-mcp-server --client claude
  109. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.