Facebook Ads MCP Server

How to use

Run the MCP server locally and connect it to your MCP client. You can ask natural language questions like: which ad accounts do I have access to, what are the active campaigns for a given account, show me metrics for a specific campaign, or pull insights for an ad set. Use the MCP client’s workflow to send requests to the server, which will fetch data from Facebook Ads API and return structured results.

How to install

Prerequisites: Python 3.10 or higher, a Facebook Developer account with Ads API access, and an access token with ads_read permission.

1. Clone or download the project directory. 2. Create and activate a virtual environment. 3. Install dependencies from the requirements file.

cd fb-ads-mcp-server
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Running the server locally

Start the server by providing your Facebook access token via the --fb-token flag.

python server.py --fb-token YOUR_FACEBOOK_ACCESS_TOKEN

Claude Desktop configuration (MCP integration)

Configure each MCP connection to point to the local server so Claude Desktop can route queries to it.

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": [
        "server.py",
        "--fb-token",
        "YOUR_FACEBOOK_ACCESS_TOKEN"
      ]
    }
  }
}

Alternative local run with a virtual environment

If you use a virtual environment, point to the Python executable inside the venv for the MCP server process.

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

Windows-specific configuration example

On Windows, you can pass the server path as an argument to the Python command.

{
  "mcpServers": {
    "fb-ads-mcp-server": {
      "command": "python",
      "args": [
        "C:\\absolute\\path\\to\\fb-ads-mcp-server\\server.py",
        "--fb-token",
        "YOUR_FACEBOOK_ACCESS_TOKEN"
      ]
    }
  }
}

Security and best practices

- Use a token with only ads_read permission for read-only access. Avoid hardcoding tokens in configuration files. Prefer secure storage and routine token rotation.

- Do not commit tokens to version control. Rotate tokens regularly and monitor API activity in the Meta Developer dashboard.

Troubleshooting

If you see a missing token error, ensure you started the server with the --fb-token option. If the token is invalid or expired, regenerate a new token with the required permission. For rate limits or network issues, retry with backoff and consider caching frequently accessed data.

Notes on API version and data access

The server uses Facebook Graph API for read-only access to ad accounts, campaigns, ad sets, ads, and insights. Ensure your token is valid for the API version in use and that your app has the necessary Ads API access.

Frequently accessed data endpoints you can query

You can retrieve accounts, campaigns, ad sets, ads, and insights. Typical actions include listing accounts, filtering campaigns by status, getting detailed campaign/ad set/ad information, and fetching performance metrics such as impressions, clicks, spend, CTR, and more.

list_ad_accounts

List all ad accounts linked to your access token.

get_details_of_ad_account

Fetch detailed information about a specific ad account.

get_campaigns_by_adaccount

Retrieve all campaigns for a given ad account, with optional fields and filters.

get_campaign_by_id

Get detailed information for a specific campaign by its ID.

get_adsets_by_campaign

Retrieve all ad sets within a campaign, with optional fields and limits.

get_adset_by_id

Get detailed information for a specific ad set by its ID.

get_ads_by_adset

Retrieve all ads within an ad set, with optional fields and limits.

get_ad_by_id

Get detailed information for a specific ad by its ID.

get_campaign_insights

Get performance metrics for a campaign over a date range or presets.

get_adset_insights

Get performance metrics for an ad set.

get_ad_insights

Get performance metrics for a specific ad.

get_summary_report

Get a lightweight summary with key metrics for quick contexts.

fetch_pagination_url

Fetch the next/previous page URL for paginated results.