facebook-ads

This MCP server provides a programmatic interface to Meta (Facebook) Ads through a set of tools that let you read account data, fetch campaigns, ad sets, ads, creatives, and insights. The server exposes methods such as list_ad_accounts, get_details_of_ad_account, get_campaign_by_id, get_ads_by_adaccount, get_ad_insights, and many related fetchers for campaigns, ad sets, ads, and creatives. It also includes activity history endpoints to retrieve change history for ad accounts and ad sets. To use it with an MCP client, configure the client to point to this server and supply a Meta Access Token (via the --fb-token argument in the example configuration). If you don’t provide a token, the integration can connect to GoMarble’s server to obtain a token on your behalf during setup, keeping your token local on your machine.

Prerequisites:

• Python 3.10+
• Dependencies listed in requirements.txt

1. (Optional but Recommended) Create and activate a virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   

2. Install dependencies:

   pip install -r requirements.txt
   

3. Obtain a Meta Access Token (ads_read or required permissions) from the Meta Developer portal. Keep this token ready to pass to the server via the --fb-token flag during startup or configuration.

4. Run the server (example):

   python server.py --fb-token YOUR_META_ACCESS_TOKEN
   

5. If integrating with an MCP client, add a configuration similar to the example in the README, replacing the path to server.py and the token as needed. Restart the MCP Client after updating configuration.

Tips and caveats:

• If your Meta access token expires, generate a new token and update the MCP Client configuration with the new token.
• The server is designed to connect to GoMarble's server to obtain a token on your behalf if you choose not to supply one directly during setup; note that the token is stored locally on your machine for use with the MCP server.
• Most MCP tools support additional parameters such as fields, filtering, limit, pagination, and date ranges—refer to the detailed docstrings within server.py for the full list and usage.
• If running in a virtual environment, you may need to specify the Python executable inside the venv in your MCP configuration (see commented examples in the README).
• For Windows users, command syntax adjustments may be required (e.g., using cmd /k).