Meta Ads MCP

Instructions

Implementation Reference

• meta_ads_mcp/core/openai_deep_research.py:366-413 (handler)

  The 'fetch' tool handler: async function that takes an 'id' parameter, retrieves the corresponding record from the cache using _data_manager.fetch_record(id), and returns formatted JSON with id, title, text, metadata.
  @mcp_server.tool() async def fetch( id: str ) -> str: """ Fetch complete record data by ID. It retrieves the full data for a specific record identified by its ID. Args: id: The record ID to fetch (format: "type:id", e.g., "account:act_123456") Returns: JSON response with complete record data including id, title, text, and metadata Example Usage: fetch(id="account:act_123456789") fetch(id="campaign:23842588888640185") fetch(id="ad:23842614006130185") fetch(id="page:123456789") """ if not id: return json.dumps({ "error": "id parameter is required" }, indent=2) try: # Use the data manager to fetch the record record = _data_manager.fetch_record(id) if record: logger.info(f"Record fetched successfully: {id}") return json.dumps(record, indent=2) else: logger.warning(f"Record not found: {id}") return json.dumps({ "error": f"Record not found: {id}", "id": id }, indent=2) except Exception as e: error_msg = str(e) logger.error(f"Error in fetch tool: {error_msg}") return json.dumps({ "error": "Failed to fetch record", "details": error_msg, "id": id }, indent=2)
• meta_ads_mcp/core/openai_deep_research.py:286-304 (helper)

  Helper method in MetaAdsDataManager class that implements the core fetch logic by retrieving records from the internal cache populated during search operations.
  def fetch_record(self, record_id: str) -> Optional[Dict[str, Any]]: """Fetch a cached record by ID Args: record_id: The record ID to fetch Returns: Record data or None if not found """ logger.info(f"Fetching record: {record_id}") record = self._cache.get(record_id) if record: logger.debug(f"Record found in cache: {record['type']}") return record else: logger.warning(f"Record not found in cache: {record_id}") return None
• meta_ads_mcp/core/openai_deep_research.py:366-413 (registration)

  Tool registration via the @mcp_server.tool() decorator on the fetch function, which registers it with the MCP server under the name 'fetch'.
  @mcp_server.tool() async def fetch( id: str ) -> str: """ Fetch complete record data by ID. It retrieves the full data for a specific record identified by its ID. Args: id: The record ID to fetch (format: "type:id", e.g., "account:act_123456") Returns: JSON response with complete record data including id, title, text, and metadata Example Usage: fetch(id="account:act_123456789") fetch(id="campaign:23842588888640185") fetch(id="ad:23842614006130185") fetch(id="page:123456789") """ if not id: return json.dumps({ "error": "id parameter is required" }, indent=2) try: # Use the data manager to fetch the record record = _data_manager.fetch_record(id) if record: logger.info(f"Record fetched successfully: {id}") return json.dumps(record, indent=2) else: logger.warning(f"Record not found: {id}") return json.dumps({ "error": f"Record not found: {id}", "id": id }, indent=2) except Exception as e: error_msg = str(e) logger.error(f"Error in fetch tool: {error_msg}") return json.dumps({ "error": "Failed to fetch record", "details": error_msg, "id": id }, indent=2)
• meta_ads_mcp/core/openai_deep_research.py:307-307 (helper)

  Global instance of MetaAdsDataManager used by both search and fetch tools to manage cached data.
  _data_manager = MetaAdsDataManager()
• meta_ads_mcp/core/server.py:343-344 (registration)

  Import statement in server.py that loads the openai_deep_research module, triggering registration of the 'fetch' tool via its decorators.
  from . import accounts, campaigns, adsets, ads, insights, authentication from . import ads_library, budget_schedules, reports, openai_deep_research