Meta Ads MCP

Instructions

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")

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