Facebook Ads MCP Server

What is Facebook Ads MCP Server about?

The server acts as a bridge between Meta (Facebook) Ads and Model Context Protocol (MCP) clients, exposing a comprehensive set of tools that read, list, and analyze ad accounts, campaigns, ad sets, ads, creatives, insights, and activity logs.

How to use Facebook Ads MCP Server?

Prerequisites – Install Python 3.10+ and clone the repository.
(Optional) Create a virtual environment and activate it.
Install dependencies with pip install -r requirements.txt.
Obtain a Meta User Access Token (or let the installer generate one on your behalf).

Launch the server:

python server.py --fb-token YOUR_META_ACCESS_TOKEN

Add the server to an MCP‑compatible client (e.g., Claude Desktop, Cursor) using a JSON configuration similar to:

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": ["/path/to/server.py", "--fb-token", "YOUR_META_ACCESS_TOKEN"]
    }
  }
}

Restart the client after updating the configuration.

Key features of Facebook Ads MCP Server

Account & Object Read – List ad accounts, retrieve details for specific accounts, campaigns, ad sets, ads, and creatives.
Collection Fetching – Pull campaigns, ad sets, ads, and creatives by account or hierarchy (campaign → ad set → ad).
Insights & Performance – Access ad‑account, campaign, ad‑set, and ad insights with full support for fields, filtering, date ranges, pagination, and limits.
Activity History – Retrieve change‑log activities for accounts and ad sets.
Pagination Helper – fetch_pagination_url utility to follow Graph API pagination links.
One‑Click Installer – Optional installer that can generate a Meta token automatically, removing the need for manual token creation.

Use cases of Facebook Ads MCP Server

Automated Reporting – Generate periodic performance dashboards by querying insights via MCP clients.
Ad Management Bots – Build agents that create, pause, or adjust ads based on real‑time metrics.
Data Integration – Sync Meta Ads data into internal BI platforms or data warehouses.
Audit & Compliance – Pull activity logs to monitor changes and ensure policy compliance.
Cross‑Channel Analysis – Combine Meta Ads data with other marketing sources (e.g., Google Ads) for unified reporting.

FAQ from the Facebook Ads MCP Server

Do I need a Meta Developer token? No. The optional installer can obtain a token via GoMarble’s service; the token is stored locally only.
What Python version is required? Python 3.10 or later.
Can I run the server without a virtual environment? Yes, but a virtual environment is recommended to isolate dependencies.
How do I refresh an expired token? Generate a new token from the Meta Developer portal or use the installer again, then update the --fb-token value in the MCP client configuration.
Is there a Node.js version of the server? Currently the server is implemented in Python; integration is achieved through the MCP client configuration.

Facebook/Meta Ads MCP Server

This project provides an MCP server acting as an interface to the Meta Ads, enabling programmatic access to Meta Ads data and management features.

Your browser does not support the video tag.

Easy One-Click Setup

For a simpler setup experience, we offer ready-to-use installers:

👉 Download installer - https://gomarble.ai/mcp

Join our community for help and updates

👉 Slack Community - AI in Ads

Try Google ads mcp server also

👉 Google Ads MCP - Google Ads MCP

What It Does

Installs and configures the MCP server locally
Automatically handles environment setup
Prompts for Meta token authentication during the process which is optional
If Meta access token is not provided then connect to GoMarble's server to create the token on your behalf

Important Disclaimer

This setup does not require you to manually obtain a Meta Developer Access Token.

Instead, it connects securely to GoMarble's server to create the token on your behalf. GoMarble does not store your token — it is saved locally on your machine for use with the MCP server.

Setup

Prerequisites

Python 3.10+
Dependencies listed in requirements.txt

(Optional but Recommended) Create and Activate a Virtual Environment:
```
python3 -m venv venv
source venv/bin/activate  # On Windows use `venv\Scripts\activate`
```
Using a virtual environment helps manage project dependencies cleanly[Source].
Install Dependencies:
```
pip install -r requirements.txt
```
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.

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

To integrate this server with an MCP-compatible client, add a configuration(Claude) 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
`get_adaccount_insights`	Retrieves performance insights for an ad account.
`get_campaign_insights`	Retrieves performance insights for a campaign.
`get_adset_insights`	Retrieves performance insights for an ad set.
`get_ad_insights`	Retrieves performance insights for an ad.
`fetch_pagination_url`	Fetches data from a pagination URL (e.g., from insights).
Activity/Change History
`get_activities_by_adaccount`	Retrieves change history for an ad account.
`get_activities_by_adset`	Retrieves change history for an ad set.

(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.)

(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.)

Dependencies

mcp (>=1.6.0)
requests (>=2.32.3)

License

This project is licensed under the MIT License.

Installing via Smithery

To install Facebook Ads Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @gomarble-ai/facebook-ads-mcp-server --client claude

{ "mcpServers": { "facebook-ads-mcp-server": { "command": "python", "args": [ "server.py", "--fb-token", "<YOUR_META_ACCESS_TOKEN>" ], "env": {} } } }