Meta Ads MCP

Meta Ads MCP is licensed under the Business Source License 1.1.

Key terms:

• Free to use for both individual and business purposes.
• Modify and customize as needed.
• Redistribute to others is permitted.
• Open Source Transition: The project becomes fully open source under the Apache 2.0 license on January 1, 2029.

Restriction: You may not offer this software as a competing hosted service. For commercial licensing inquiries, contact Pipeboard.

When working with frequency cap settings (frequency_control_specs), be aware that visibility in API responses is dependent on the optimization goal.

• Visibility: Frequency caps are only visible in API responses for ad sets where the optimization goal is set to REACH.
• Behavior for other goals: For optimization goals such as LINK_CLICKS or CONVERSIONS, frequency caps will still function as configured, but the settings will not be visible via the API.

To verify that frequency caps are active when they are not visible in the API, monitor these signals:

1. The frequency metric in ad insights.
2. The ratio between reach and impressions over time.
3. The actual frequency cap behavior within the Meta Ads Manager UI.

Meta Ads MCP implements secure token management and automatic authentication handling. The security model depends on your deployment method:

• Remote MCP: Authentication is handled entirely in the cloud; no local token storage is required on your machine.
• Local Installation: Tokens are cached securely on your local machine.

The HTTP transport uses a per-request authentication model. This is critical for security when exposing the server over a network.

• No Implicit Fallback: Unlike stdio mode, the server will not use the META_ACCESS_TOKEN environment variable as an implicit fallback for incoming HTTP requests. If a request lacks a token header, it is rejected with 401 Unauthorized.
• Required Headers: Every request must include one of the following:
  • Authorization: Bearer <token> (Recommended)
  • X-META-ACCESS-TOKEN: <token>
  • X-PIPEBOARD-API-TOKEN: <token> (Legacy)
• Operational Safety:
  • Do not expose the raw port to untrusted networks.
  • If using --host 0.0.0.0, place the server behind an authenticating reverse proxy.
  • Avoid setting META_ACCESS_TOKEN on network-exposed servers to prevent accidental credential leakage.

When consuming Meta Marketing API responses, a missing field does not always indicate that a setting is unset. You should account for the following behaviors:

• Field Visibility: Some fields may not appear in API responses even when explicitly requested. This is a known API limitation where the field is set but not visible.
• Response Filtering: The API may omit empty or default values to reduce payload size. A missing field may mean:
  • The field is not set.
  • The field has a default value.
  • The field is not applicable to the current configuration.

Best Practices:

• Always cross-reference important changes using both the API and the Meta Ads Manager UI.
• Use insights and metrics to confirm behavioral changes when direct field access is limited.

To use Meta Ads with Claude:

1. Navigate to claude.ai/settings/integrations.
2. Click "Add Integration".
3. Use the following details:
   • Name: Pipeboard Meta Ads
   • Integration URL: https://meta-ads.mcp.pipeboard.co/
4. Follow the prompts to login to Pipeboard and connect your Facebook Ads account.

Advanced: Direct Token Authentication To bypass the interactive flow, append your Pipeboard API token (retrieved from pipeboard.co/api-tokens) to the URL: https://meta-ads.mcp.pipeboard.co/?token=YOUR_PIPEBOARD_TOKEN

If you need to support both local MCP clients (like Claude Desktop or Cursor) and web applications, you can run both transports simultaneously by running two separate instances of the application. The application can only run in one mode at a time.

1. For stdio (Local Clients): Keep your existing setup. Authentication is handled via the PIPEBOARD_API_TOKEN environment variable.
2. For HTTP (Web/Custom Integrations): Run a separate server instance using the --transport streamable-http flag. Authentication is handled by passing the token in the Authorization: Bearer <token> header.

Both transports provide access to the same Meta Ads functionality and share the same underlying authentication system.

To verify that the Streamable HTTP server is running and responding correctly, send a tools/list request using curl. This tests the endpoint, authentication, and JSON-RPC handling.

curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your_token" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

To ensure your Meta Ads MCP connection is working correctly within your MCP client, perform these three verification steps:

1. Verify Account Access: Ask your LLM to call mcp_meta_ads_get_ad_accounts.
2. Check Account Details: Use mcp_meta_ads_get_account_info with your specific account ID.
3. List Campaigns: Call mcp_meta_ads_get_campaigns to confirm you can retrieve your ad campaigns.

The Pipeboard CLI is a single Go binary that exposes all MCP tools as typed shell commands. This is ideal for automation scripts or AI coding agents (like Claude Code or Cline) that prefer subprocess calls over JSON-RPC.

Installation (macOS):

brew install pipeboard-co/tap/pipeboard

Usage: You must export your PIPEBOARD_API_TOKEN before running commands.

export PIPEBOARD_API_TOKEN=<your-token>

# Example: Get Meta Ads campaigns
pipeboard meta-ads get-campaigns --account-id act_123

# Example: Execute a Google Ads GAQL query
pipeboard google-ads execute-gaql-query --customer-id 1234567890 --query "..."

# Example: Get TikTok Ads campaigns
pipeboard tiktok-ads get-campaigns --advertiser-id 7605685552884596737