How to integrate Metaads MCP with LlamaIndex

Connect LlamaIndex to Metaads MCP. Get ad performance insights for last week, create a new campaign for summer sale, and more using natural language, with authentication handled for you.

Metaads logoMetaads
Oauth2Api Key

Metaads is Meta's official Ads API that lets you manage, analyze, and optimize your Facebook and Instagram ad campaigns. Streamline ad operations and gain deeper insights with robust automation.

70 Tools

Introduction

This guide walks you through connecting Metaads to LlamaIndex using the Composio tool router. By the end, you'll have a working Metaads agent that can get ad performance insights for last week, create a new campaign for summer sale, pause all ads in underperforming campaigns through natural language commands.

This guide will help you understand how to give your LlamaIndex agent real control over a Metaads account through Composio's Metaads MCP server.

Before we dive in, let's take a quick look at the key ideas and tools involved.

Also integrate Metaads with

TL;DR

Here's what you'll learn:
  • Set your OpenAI and Composio API keys
  • Install LlamaIndex and Composio packages
  • Create a Composio Tool Router session for Metaads
  • Connect LlamaIndex to the Metaads MCP server
  • Build a Metaads-powered agent using LlamaIndex
  • Interact with Metaads through natural language

What is LlamaIndex?

LlamaIndex is a data framework for building LLM applications. It provides tools for connecting LLMs to external data sources and services through agents and tools.

Key features include:

  • ReAct Agent: Reasoning and acting pattern for tool-using agents
  • MCP Tools: Native support for Model Context Protocol
  • Context Management: Maintain conversation context across interactions
  • Async Support: Built for async/await patterns

What is the Metaads MCP server, and what's possible with it?

The Meta Ads MCP server is an implementation of the Model Context Protocol that connects your AI agent and assistants like Claude, Cursor, etc directly to your Meta Ads account. It provides structured and secure access to your campaigns, ads, audiences, leads, performance insights, and business assets, so your agent can create campaigns, build ads, update campaigns, analyze results, and retrieve leads on your behalf.

  • Campaign and ad creation: Have your agent create campaigns, ad sets, ad creatives, and ads for your Meta advertising account.
  • Campaign updates: Direct your agent to update existing campaigns when your advertising plans or settings change.
  • Performance analysis: Let the agent retrieve insights for your advertising account, campaigns, ad sets, or ads to help you review results.
  • Audience and targeting research: Instruct your agent to create custom audiences and search available targeting options for upcoming campaigns.
  • Lead and asset discovery: Have your agent retrieve leads and list accessible businesses, advertising accounts, Facebook Pages, Instagram assets, campaigns, ads, and creatives.

What is the Composio tool router, and how does it fit here?

What is Composio SDK?

Composio's Composio SDK helps agents find the right tools for a task at runtime. You can plug in multiple toolkits (like Gmail, HubSpot, and GitHub), and the agent will identify the relevant app and action to complete multi-step workflows. This can reduce token usage and improve the reliability of tool calls. Read more here: Getting started with Composio SDK

The tool router generates a secure MCP URL that your agents can access to perform actions.

How the Composio SDK works

The Composio SDK follows a three-phase workflow:

  1. Discovery: Searches for tools matching your task and returns relevant toolkits with their details.
  2. Authentication: Checks for active connections. If missing, creates an auth config and returns a connection URL via Auth Link.
  3. Execution: Executes the action using the authenticated connection.

Step-by-step Guide

Step by step10 STEPS
1

Prerequisites

Before you begin, make sure you have:
  • Python 3.8/Node 16 or higher installed
  • A Composio account with the API key
  • An OpenAI API key
  • A Metaads account and project
  • Basic familiarity with async Python/Typescript
2

Getting API Keys for OpenAI, Composio, and Metaads

OpenAI API key (OPENAI_API_KEY)
  • Go to the OpenAI dashboard
  • Create an API key if you don't have one
  • Assign it to OPENAI_API_KEY in .env
Composio API key and user ID
  • Log into the Composio dashboard
  • Copy your API key from Settings
    • Use this as COMPOSIO_API_KEY
  • Pick a stable user identifier (email or ID)
    • Use this as COMPOSIO_USER_ID
3

Installing dependencies

npm install @composio/llamaindex @llamaindex/openai @llamaindex/tools @llamaindex/workflow dotenv

Create a new Typescript project and install the necessary dependencies:

  • @composio/llamaindex: Composio's LlamaIndex integration
  • @llamaindex/openai: OpenAI LLM integration
  • @llamaindex/tools: MCP client for LlamaIndex
  • @llamaindex/workflow: Workflow framework for LlamaIndex
  • dotenv: Environment variable management
4

Set environment variables

bash
OPENAI_API_KEY=your-openai-api-key
COMPOSIO_API_KEY=your-composio-api-key
COMPOSIO_USER_ID=your-user-id

Create a .env file in your project root:

These credentials will be used to:

  • Authenticate with OpenAI's GPT-5 model
  • Connect to Composio's Tool Router
  • Identify your Composio user session for Metaads access
5

Import modules

import "dotenv/config";
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";

import { Composio } from "@composio/core";

import { mcp } from "@llamaindex/tools";
import { agent as createAgent } from "@llamaindex/workflow";
import { openai } from "@llamaindex/openai";

dotenv.config();

Create a new file called metaads_llamaindex_agent.ts and import the required modules:

Key imports:

  • dotenv.config loads .env at runtime
  • readline gives us a simple CLI chat loop
  • Composio is the main Composio SDK client
  • mcp connects to an MCP endpoint
  • createAgent builds a LlamaIndex agent
  • openai configures the LLM backend
6

Load environment variables and initialize Composio

const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const COMPOSIO_API_KEY = process.env.COMPOSIO_API_KEY;
const COMPOSIO_USER_ID = process.env.COMPOSIO_USER_ID;

if (!OPENAI_API_KEY) throw new Error("OPENAI_API_KEY is not set");
if (!COMPOSIO_API_KEY) throw new Error("COMPOSIO_API_KEY is not set");
if (!COMPOSIO_USER_ID) throw new Error("COMPOSIO_USER_ID is not set");

What's happening:

This ensures missing credentials cause early, clear errors before the agent attempts to initialise.

7

Create a Tool Router session and build the agent function

async function buildAgent() {

  console.log(`Initializing Composio client...${COMPOSIO_USER_ID!}...`);
  console.log(`COMPOSIO_USER_ID: ${COMPOSIO_USER_ID!}...`);

  const composio = new Composio({
    apiKey: COMPOSIO_API_KEY,
    provider: new LlamaindexProvider(),
  });

  const session = await composio.create(
    COMPOSIO_USER_ID!,
    {
      toolkits: ["metaads"],
    },
  );

  const mcpUrl = session.mcp.url;
  console.log(`Composio Tool Router MCP URL: ${mcpUrl}`);

  const server = mcp({
    url: mcpUrl,
    clientName: "composio_tool_router_with_llamaindex",
    requestInit: {
      headers: {
        "x-api-key": COMPOSIO_API_KEY!,
      },
    },
    // verbose: true,
  });

  const tools = await server.tools();

  const llm = openai({ apiKey: OPENAI_API_KEY, model: "gpt-5" });

  const agent = createAgent({
    name: "composio_tool_router_with_llamaindex",
        description : "An agent that uses Composio Tool Router MCP tools to perform actions.",
    systemPrompt:
      "You are a helpful assistant connected to Composio Tool Router."+
"Use the available tools to answer user queries and perform Metaads actions." ,
    llm,
    tools,
  });

  return agent;
}

What's happening here:

  • We create a Composio client using your API key and configure it with the LlamaIndex provider
  • We then create a tool router MCP session for your user, specifying the toolkits we want to use (in this case, metaads)
  • The session returns an MCP HTTP endpoint URL that acts as a gateway to all your configured tools
  • LlamaIndex will connect to this endpoint to dynamically discover and use the available Metaads tools.
  • The MCP tools are mapped to LlamaIndex-compatible tools and plug them into the Agent.
8

Create an interactive chat loop

async function chatLoop(agent: ReturnType<typeof createAgent>) {
  const rl = readline.createInterface({ input, output });

  console.log("Type 'quit' or 'exit' to stop.");

  while (true) {
    let userInput: string;

    try {
      userInput = (await rl.question("\nYou: ")).trim();
    } catch {
      console.log("\nAgent: Bye!");
      break;
    }

    if (!userInput) {
      continue;
    }

    const lower = userInput.toLowerCase();
    if (lower === "quit" || lower === "exit") {
      console.log("Agent: Bye!");
      break;
    }

    try {
      process.stdout.write("Agent: ");

      const stream = agent.runStream(userInput);
      let finalResult: any = null;

      for await (const event of stream) {
        // The event.data contains the streamed content
        const data: any = event.data;

        // Check for streaming delta content
        if (data?.delta) {
          process.stdout.write(data.delta);
        }

        // Store final result for fallback
        if (data?.result || data?.message) {
          finalResult = data;
        }
      }

      // If no streaming happened, show the final result
      if (finalResult) {
        const answer =
          finalResult.result ??
          finalResult.message?.content ??
          finalResult.message ??
          "";
        if (answer && typeof answer === "string" && !answer.includes("[object")) {
          process.stdout.write(answer);
        }
      }

      console.log(); // New line after streaming completes
    } catch (err: any) {
      console.error("\nAgent error:", err?.message ?? err);
    }
  }

  rl.close();
}

What's happening:

  • We're creating a direct terminal interface to chat with Metaads
  • The LLM's responses are streamed to the CLI for faster interaction.
  • The agent uses context to maintain conversation history
  • The agent processes the request, selects appropriate Metaads tools, and returns a result
  • We extract the answer from the result data structure and display it to the user
  • You can type 'quit' or 'exit' to stop the chat loop gracefully
  • Agent responses and any errors are streamed in a clear, readable format
9

Define the main entry point

async function main() {
  try {
    const agent = await buildAgent();
    await chatLoop(agent);
  } catch (err) {
    console.error("Failed to start agent:", err);
    process.exit(1);
  }
}

main();

What's happening here:

  • We're orchestrating the entire application flow
  • The agent gets built with proper error handling
  • Then we kick off the interactive chat loop so you can start talking to Metaads
10

Run the agent

npx ts-node llamaindex-agent.ts

When prompted, authenticate and authorise your agent with Metaads, then start asking questions.

Complete Code

Here's the complete code to get you started with Metaads and LlamaIndex:

import "dotenv/config";
import readline from "node:readline/promises";
import { stdin as input, stdout as output } from "node:process";

import { Composio } from "@composio/core";
import { LlamaindexProvider } from "@composio/llamaindex";

import { mcp } from "@llamaindex/tools";
import { agent as createAgent } from "@llamaindex/workflow";
import { openai } from "@llamaindex/openai";

dotenv.config();

const OPENAI_API_KEY = process.env.OPENAI_API_KEY;
const COMPOSIO_API_KEY = process.env.COMPOSIO_API_KEY;
const COMPOSIO_USER_ID = process.env.COMPOSIO_USER_ID;

if (!OPENAI_API_KEY) {
    throw new Error("OPENAI_API_KEY is not set in the environment");
  }
if (!COMPOSIO_API_KEY) {
    throw new Error("COMPOSIO_API_KEY is not set in the environment");
  }
if (!COMPOSIO_USER_ID) {
    throw new Error("COMPOSIO_USER_ID is not set in the environment");
  }

async function buildAgent() {

  console.log(`Initializing Composio client...${COMPOSIO_USER_ID!}...`);
  console.log(`COMPOSIO_USER_ID: ${COMPOSIO_USER_ID!}...`);

  const composio = new Composio({
    apiKey: COMPOSIO_API_KEY,
    provider: new LlamaindexProvider(),
  });

  const session = await composio.create(
    COMPOSIO_USER_ID!,
    {
      toolkits: ["metaads"],
    },
  );

  const mcpUrl = session.mcp.url;
  console.log(`Composio Tool Router MCP URL: ${mcpUrl}`);

  const server = mcp({
    url: mcpUrl,
    clientName: "composio_tool_router_with_llamaindex",
    requestInit: {
      headers: {
        "x-api-key": COMPOSIO_API_KEY!,
      },
    },
    // verbose: true,
  });

  const tools = await server.tools();

  const llm = openai({ apiKey: OPENAI_API_KEY, model: "gpt-5" });

  const agent = createAgent({
    name: "composio_tool_router_with_llamaindex",
    description:
      "An agent that uses Composio Tool Router MCP tools to perform actions.",
    systemPrompt:
      "You are a helpful assistant connected to Composio Tool Router."+
"Use the available tools to answer user queries and perform Metaads actions." ,
    llm,
    tools,
  });

  return agent;
}

async function chatLoop(agent: ReturnType<typeof createAgent>) {
  const rl = readline.createInterface({ input, output });

  console.log("Type 'quit' or 'exit' to stop.");

  while (true) {
    let userInput: string;

    try {
      userInput = (await rl.question("\nYou: ")).trim();
    } catch {
      console.log("\nAgent: Bye!");
      break;
    }

    if (!userInput) {
      continue;
    }

    const lower = userInput.toLowerCase();
    if (lower === "quit" || lower === "exit") {
      console.log("Agent: Bye!");
      break;
    }

    try {
      process.stdout.write("Agent: ");

      const stream = agent.runStream(userInput);
      let finalResult: any = null;

      for await (const event of stream) {
        // The event.data contains the streamed content
        const data: any = event.data;

        // Check for streaming delta content
        if (data?.delta) {
          process.stdout.write(data.delta);
        }

        // Store final result for fallback
        if (data?.result || data?.message) {
          finalResult = data;
        }
      }

      // If no streaming happened, show the final result
      if (finalResult) {
        const answer =
          finalResult.result ??
          finalResult.message?.content ??
          finalResult.message ??
          "";
        if (answer && typeof answer === "string" && !answer.includes("[object")) {
          process.stdout.write(answer);
        }
      }

      console.log(); // New line after streaming completes
    } catch (err: any) {
      console.error("\nAgent error:", err?.message ?? err);
    }
  }

  rl.close();
}

async function main() {
  try {
    const agent = await buildAgent();
    await chatLoop(agent);
  } catch (err: any) {
    console.error("Failed to start agent:", err?.message ?? err);
    process.exit(1);
  }
}

main();

Conclusion

You've successfully connected Metaads to LlamaIndex through Composio's Tool Router MCP layer. Key takeaways:
  • Tool Router dynamically exposes Metaads tools through an MCP endpoint
  • LlamaIndex's ReActAgent handles reasoning and orchestration; Composio handles integrations
  • The agent becomes more capable without increasing prompt size
  • Async Python provides clean, efficient execution of agent workflows
You can easily extend this to other toolkits like Gmail, Notion, Stripe, GitHub, and more by adding them to the toolkits parameter.
TOOLS

Supported Tools

Every Metaads action and event your agent gets out of the box.

Copy Ad Object

Copy a Meta Campaign, Ad Set, or Ad while explicitly selecting its resource type and supported copy options.

Create Ad

Create a new ad within an ad set using the Meta Marketing API.

Create Ad Creative

Create a new ad creative using the Meta Marketing API.

Create Ad Set

Create a new ad set within a campaign using the Meta Marketing API.

Create Ad Video

Upload an ad video asset; Meta may keep processing it after returning its ID.

Create Campaign

Create a new advertising campaign using the Meta Marketing API.

Create Custom Audience

Create a new custom audience using the Meta Marketing API.

Create Custom Conversion

Create a persistent custom-conversion definition in a Meta ad account and return its ID.

Create Lead Form

Create a persistent lead-generation form owned by a Facebook Page and return its ID.

Delete Campaign

Delete an advertising campaign using the Meta Marketing API.

Generate Ad Previews

Render previews for a provider-native creative specification in a Meta ad account and return the generated HTML bodies.

Get Ad Accounts

Tool to retrieve all ad account IDs accessible to the authenticated user from Meta Ads.

Get Ad Creative

Get Ad Creative

Get Insights

Get insights data for a Meta Ads object (ad account, campaign, ad set, or ad) using the Meta Marketing API.

Get Meta Object

Tool to retrieve data for any Meta Marketing API object by its ID.

Get Page Accounts

Retrieve pages managed by the authenticated user, including page access tokens when requested.

Get Pixel Event Stats

Read recent Pixel event-count and processing statistics, optionally restricted to server events and one event name, to verify aggregate ingestion.

Get User

Tool to retrieve information about the authenticated user from Meta (Facebook) Graph API.

List Activities

List activity history for a Meta ad account or ad set.

List Ad Account Pixels

List the Pixels and consolidated datasets associated with an ad account so a usable data-source ID can be selected for Conversions API events.

List Ad Creatives

Tool to list all ad creatives under an ad account.

List Ad Images

List one page of image assets in a Meta ad account, optionally restricted to exact image hashes.

List Ad Network Analytics

Tool to retrieve ad network analytics for a Meta Business using the Meta Marketing API.

List Ad Network Analytics Results

Tool to retrieve ad network analytics results for Facebook Audience Network.

List Ads

Tool to list all ads under an ad account using the Meta Marketing API.

List Ad Videos

List one page of video assets in a Meta ad account, optionally filtered by title, dimensions, duration, or aspect ratio.

List Agencies

Tool to retrieve agencies associated with a Meta Business or Ad Account.

List Assigned Pages

Tool to retrieve Facebook Pages assigned to a business user via Meta Marketing API.

List Assigned Users

Tool to list users assigned to a Facebook Page or Ad Account within a specific business context.

List Business Ad Accounts

Tool to retrieve all ad accounts owned by a specific Business Manager.

List Businesses

Tool to discover every Business Manager the authenticated Meta principal can access, via `GET /me/businesses`.

List Business Invoices

Tool to retrieve business invoices from Meta Marketing API.

List Campaigns

List one page of campaigns belonging to a Meta ad account.

List Client Ad Accounts

Tool to list all client ad accounts accessible to a business from Meta Ads.

List Client Apps

Tool to retrieve client apps associated with a Meta Business using the Marketing API.

List Client Instagram Assets

Tool to retrieve Instagram assets that are shared with a business as a client using the Meta Marketing API.

List Client Offsite Signal Container Business Objects

Tool to retrieve client offsite signal container business objects for a business from Meta Marketing API.

List Client Pages

Tool to retrieve client pages associated with a Meta business.

List Clients

Tool to retrieve client businesses associated with a Meta Business Manager.

List Collaborative Ads Collaboration Requests

Tool to retrieve collaborative ads collaboration requests for a Meta Business using the Marketing API.

List Collaborative Ads Suggested Partners

Tool to retrieve collaborative ads suggested partners for a business from Meta Marketing API.

List Comments

Return one page from the comments edge of a Page-owned post, photo, video, comment, or reply.

List Custom Audiences

List one page of custom audiences in a Meta ad account, with field projection and optional business, primary-audience, or Pixel constraints.

List Custom Conversions

List one page of custom-conversion definitions in a Meta ad account, with field projection and opaque cursor pagination.

List Initiated Audience Sharing Requests

Tool to retrieve initiated audience sharing requests for a business using the Meta Marketing API.

List Leads

List one page of leads belonging to a Meta Ad or Leadgen Form.

List Managed Partner Ads Funding Source Details

Tool to retrieve managed partner ads funding source details for a Meta Business.

List Owned Apps

Tool to retrieve apps owned by a business from Meta Marketing API.

List Owned Businesses

Tool to retrieve businesses owned by a parent Business Manager from Meta Marketing API.

List Owned Instagram Assets

Tool to list Instagram accounts/assets owned by a Meta Business.

List Owned Offsite Signal Container Business Objects

Tool to retrieve owned offsite signal container business objects for a business from Meta Marketing API.

List Owned Pages

Tool to retrieve Pages owned by a Business Manager from Meta Marketing API.

List Pending Client Ad Accounts

Tool to retrieve pending client ad account access requests for a Business Manager from Meta Ads.

List Pending Client Apps

Tool to retrieve pending client apps for a Meta Business.

List Pending Client Pages

Tool to retrieve pending client pages for a Business Manager using the Meta Marketing API.

List Pending Shared Offsite Signal Container Business Objects

Tool to retrieve pending shared offsite signal container business objects from Meta Marketing API.

List Pending Owned Ad Accounts

Tool to retrieve pending owned ad accounts for a Business Manager account from Meta Marketing API.

List Pending Owned Pages

Tool to retrieve Pages with pending ownership status for a Business Manager from Meta Marketing API.

List Pending Users

Tool to retrieve pending users from a Business Manager in Meta Marketing API.

List Received Audience Sharing Requests

Tool to retrieve all received audience sharing requests for a business using the Meta Marketing API.

List Subscribed Apps

List one page of applications subscribed to a Meta ad account.

List System Users

Tool to retrieve system users for a Meta Business Manager account.

List Targeting Search

Tool to search for targeting options in Meta Ads Marketing API.

List Video Tags

Return one page of TaggableSubject entries from a Video's `/tags` edge.

List Video Thumbnails

List one page of available thumbnail variants for a Meta video.

Read Ad Sets

Retrieve ad sets from a Meta ad account using the Marketing API.

Send Conversion Events

Irreversibly submit 1-1,000 validated server conversion events to a Meta Pixel or dataset.

Update Ad Creative

Update Ad Creative

Update Campaign

Update an existing advertising campaign using the Meta Marketing API.

Upload Ad Image

Upload an image for use in Meta ad creatives using the Marketing API.

FAQ

Frequently asked questions

With a standalone Metaads MCP server, the agents and LLMs can only access a fixed set of Metaads tools tied to that server. However, with the Composio Tool Router, agents can dynamically load tools from Metaads and many other apps based on the task at hand, all through a single MCP endpoint.

Yes, you can. LlamaIndex fully supports MCP integration. You get structured tool calling, message history handling, and model orchestration while Tool Router takes care of discovering and serving the right Metaads tools.

Yes, absolutely. You can configure which Metaads scopes and actions are allowed when connecting your account to Composio. You can also bring your own OAuth credentials or API configuration so you keep full control over what the agent can do.

All sensitive data such as tokens, keys, and configuration is fully encrypted at rest and in transit. Composio is SOC 2 Type 2 compliant and follows strict security practices so your Metaads data and credentials are handled as safely as possible.

Start with Metaads.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Metaads tool your agent needs.Free to start.

Start building