Using an MCP server to query Meta Ads API for AI-driven ad insights

AI agents querying advertising data face the challenge of interfacing with complex APIs like Meta’s Graph API. The gomarble-ai/facebook-ads-mcp-server repo addresses this by wrapping Facebook Ads API endpoints into a Model Context Protocol (MCP) server implemented in Python. This lets AI models like Claude Desktop or Cursor interact with Facebook Ads data as structured tools, enabling conversational ad performance queries and insights.

wrapping Meta Ads API behind MCP tools

At its core, this repo exposes the Meta (Facebook) Ads API as more than 20 MCP tools, covering the entire ads data hierarchy: accounts, campaigns, ad sets, ads, and creatives, plus performance insights and change history. The server is a single Python script, server.py, that wraps Meta’s Graph API endpoints into MCP tool definitions.

The MCP protocol (Model Context Protocol) is designed to let AI models securely call external tools through a standardized RPC interface. Here, each tool corresponds to an API endpoint or a logical query operation on the Facebook Ads data model. The server authenticates requests using Meta User Access Tokens with ads_read permissions.

The architecture is straightforward — no complex microservices or middleware layers. The single Python server parses command line arguments for the access token and registers over 20 MCP tools that internally call the Facebook Graph API endpoints. This design keeps the footprint small and the codebase easy to follow.

Clients like Claude Desktop or Cursor, which support MCP, can then connect to this server and invoke these tools programmatically from AI prompts. This enables an AI agent to ask, for instance, “What are the top-performing campaigns this week?” and receive structured data fetched live from the Facebook Ads API.

technical strengths and tradeoffs

The simplicity of implementation is a clear strength: a single Python file with minimal dependencies (Python 3.10+ and standard libraries plus requests) that implements a full suite of tools over the Facebook Ads API. This makes it easy to audit, modify, and extend.

The mapping of over 20 endpoints into MCP tools is done explicitly and clearly, which helps maintain code quality. Each tool corresponds to a well-defined operation, such as fetching campaigns under an account, getting ad performance metrics, or retrieving the change history.

A tradeoff is that the monolithic single-file design might limit scalability or modularity if the project grows. Also, it only supports read operations (ads_read scope) and does not handle token refresh or management beyond accepting a user token at startup.

Security-wise, relying on user-generated access tokens means users must manage token permissions and expiration themselves. The server does not implement advanced auth flows or proxying beyond the basics.

The MCP protocol integration is well done, enabling seamless AI client interoperability without extra glue code. This solves a real problem for AI-driven ad analysis, where conversational queries need structured, reliable backend data sources.

quick start

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

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

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

verdict

This MCP server is a practical tool for developers and AI researchers looking to enable conversational AI agents with live access to Meta Facebook Ads data. Its strength lies in the straightforward wrapping of a complex API into structured MCP tools that AI clients can invoke directly.

The project is particularly relevant if you are experimenting with AI-driven ad performance analysis, reporting, or automated insights. However, it does require managing Meta access tokens and only supports read-only queries, so it’s not a full ad management solution.

The single-file, minimal dependency approach keeps the codebase accessible and easy to modify but may not scale if you want to add write capabilities, token management, or advanced caching layers.

Overall, this repo offers a solid foundation for integrating Meta Ads data into AI workflows, demonstrating the power of MCP tooling to bridge AI models and complex third-party APIs with minimal friction.

Exploring the Model Context Protocol with awesome-mcp-servers: a curated directory of MCP server implementations — awesome-mcp-servers is a curated list of Model Context Protocol (MCP) servers enabling AI models to interact securely wi
How WordPress MCP Adapter standardizes AI agent interaction with WordPress — The WordPress MCP Adapter converts WordPress’s Abilities API into the Model Context Protocol, enabling AI agents to inte
Inside Google Gemini CLI: a terminal-first AI agent with extensible Model Context Protocol — Google Gemini CLI is a TypeScript-based terminal AI agent offering direct Gemini model access, extensibility via MCP, an

→ GitHub Repo: gomarble-ai/facebook-ads-mcp-server ⭐ 318 · Python

Noureddine RAMDI / Using an MCP server to query Meta Ads API for AI-driven ad insights