Facebook Ads
Created 5 months ago
MCP server interface to Meta Ads for programmatic access.
What is Facebook Ads?
MCP server acting as an interface to the Facebook Ads, enabling programmatic access to Facebook Ads data and management features.
Documentation
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.
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
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.
- 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 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"
]
}
}
}
Restart the MCP Client app after making the update in the configuration.
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. |
Dependencies
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
Server Config
{
"mcpServers": {
"facebook-ads-server": {
"command": "npx",
"args": [
"facebook-ads"
]
}
}
}