Skip to main content
Glama
flin-meta-ads-mcp

flin-meta-ads-mcp

by flin-agency

flin-meta-ads-mcp

Read-only Meta Ads analysis in Claude: accounts, campaigns, ads, images and insights.

Claude Desktop on macOS — installable package

Apple Silicon (M1 or newer). Download the desktop package. Versioned packages and SHA-256 checksums are also available. No separate Python, uv, Homebrew or manual JSON setup is required. Intel desktop packages are not produced. The developer installation below remains available.

  1. Download the .mcpb, then open Claude Settings → Extensions → Advanced settings → Install Extension… (Extensions may be under Desktop app).

  2. Enter Meta App ID and App Secret from your administrator/password manager in extension settings. Alternatively, enter an Access Token with ads_read. Default ad account and Business Login configuration ID are optional. Never put secrets in chat.

  3. For browser login, call start_meta_login, open its login link and approve access with your Facebook/Meta account. The administrator must allow http://localhost:8765/callback in the Meta app. An existing token skips login.

  4. Call connection_status, then connection_status with check_live=true to verify Meta access (server 0.1.17 or newer). The default call is local only: auth_status=unknown with a token is expected until a live check. On older servers, use get_meta_auth_status, then list_ad_accounts for a real check.

  5. Call list_ad_accounts, select the intended account, then list_campaigns. A successful connection alone does not establish permission for every account.

Disable an older duplicate manual server entry after migration. Keep its credentials until the new installation works. SHA-256 files accompany versioned downloads. Packages are not Apple Developer ID signed/notarized; managed extension policy may block installation. Do not disable macOS protections.

Versions, updates and offline use

Claude's extension version describes the installed package. The connection_status.server_version field identifies the running server. Launcher 0.1.17 additionally reports extension_version and runtime_source: cached is a prepared PyPI environment, bundled the included fallback.

Each extension start prepares updates from official PyPI in the background. Successful updates activate at the next normal extension/Claude start, never inside a running conversation. Settings and saved login remain in place. Without internet, the last prepared server or bundled fallback still starts; Meta data requests themselves need internet. The first background download can take minutes.

One-time package migration: 0.1.14 lacks automatic updates. Packages 0.1.15–0.1.16 have automatic updates but need one replacement with 0.1.17 or newer to acquire the new compatibility bound and runtime-source reporting. Routine server updates then need no new MCPB import. Changes to the launcher or settings UI can need a new import.

The new launcher accepts stable, non-yanked versions >=0.1.15 and <0.2.0. The compatibility contract is the existing CLI, META_* settings, saved-login JSON and MCP tool inputs/status responses. The updater checks those tool contracts and a real credential-free MCP connection before atomic activation. A new minor/major version requires review and potentially a new package; arbitrary jumps are not assumed compatible. Pre-releases are excluded.

Support and manual fallback explains recovery without deleting login. Privacy covers data flow, storage, revocation and cleanup. Security links the detailed review. Browser login uses an unencrypted, owner-only local credentials file, distinct from Claude's sensitive settings.

Related MCP server: facebook-ads-mcp-server

What it does

  • Lists and reads Meta Ads accounts

  • Reads campaigns, ad sets, ads, ad images, and creatives

  • Downloads ad images as embedded files with download_ad_image

  • Gets ad previews (including preview_url links)

  • Fetches insights for account, campaign, ad set, and ad levels

  • Stays read-only in v0.1.x

Download image files

Call download_ad_image with a fresh url from list_ad_images, get_ad_image, or an image URL from get_ad_creative:

{"url": "https://scontent.example.fbcdn.net/path/to/image.jpg?signed_query=..."}

The connector fetches the image and returns metadata (filename, mime_type, size_bytes) plus a direct MCP image preview and an embedded binary resource containing the actual file. The consuming app does not need to fetch the external image URL, so its external image-domain allowlist is not involved. Saving or displaying the attachment requires the app to support MCP embedded binary resources; the resource URI is an identifier, not a hosted download link or a local filesystem path.

Supported formats: JPEG, PNG, GIF, and WebP, up to 5 MiB. Downloads use HTTPS Meta CDN subdomains (fbcdn.net, fbsbx.com), validate every redirect, and never send the Meta Graph access token to the CDN. Expired URLs require a fresh lookup. No image files are retained on the connector's disk. Existing image metadata tools keep their current behavior. Restart the connector after installing the updated code so the new tool is discovered.

Scope for v0.1.x

This release is strictly read-only.

That means:

  • No create, update, pause, resume, or delete actions

  • No automatic background token refresh; rerun browser login when access expires or is revoked

  • No generic Graph API proxy

Developer installation

Install and run the latest published PyPI release:

uvx flin-meta-ads-mcp

Install and refresh to the newest published release:

uvx --refresh flin-meta-ads-mcp

Run the latest GitHub code (main branch):

uvx --refresh --from git+https://github.com/flin-agency/flin-meta-ads-mcp.git flin-meta-ads-mcp

Manual Claude configuration

First start without an access token (v0.1.12 and later)

Configure the App ID and App Secret; no access token is needed to start the MCP server:

{
  "mcpServers": {
    "flin-meta-ads-mcp": {
      "command": "uvx",
      "args": ["--refresh", "flin-meta-ads-mcp@latest"],
      "env": {
        "META_APP_ID": "YOUR_NUMERIC_APP_ID",
        "META_APP_SECRET": "YOUR_APP_SECRET"
      }
    }
  }
}

Restart Claude and ask it to sign you in to Meta. It can call start_meta_login and show you a browser link. After approving access, ask it to check get_meta_auth_status. Once the status is ready, the Ads tools work immediately without restarting Claude. The saved login is also reused on subsequent starts.

The server remains connected when credentials are missing or expired. Ads calls then return login instructions instead of crashing the connection. If only the App Secret is configured, start_meta_login can accept your public App ID as app_id; never pass the App Secret in chat. An App Secret alone cannot identify the app for browser login.

The in-chat flow uses the local callback http://localhost:8765/callback and waits for up to three minutes without blocking MCP initialization. Your Meta app must allow that redirect and grant ads_read. For apps requiring HTTPS, use the terminal login's --manual flow described below. Multiple simultaneous login requests in one server reuse the same pending link; if another process has the callback port open, finish that login or select another configured redirect port.

Browser login (v0.1.11 and later)

You can sign in to Meta instead of manually generating and copying an access token.

  1. In your Meta app, enable Facebook Login (or Facebook Login for Business) and the ads_read permission. Copy the App ID and App Secret / App-Geheimcode from App settings > Basic.

  2. Configure the OAuth redirect to match http://localhost:8765/callback for local development. Meta's localhost HTTP exception is for development apps; use a registered HTTPS redirect with --manual if your app requires HTTPS. Development apps require the signing-in user to have an app role. Public use may require App Review.

  3. Start the login:

    uvx --refresh flin-meta-ads-mcp login

    Enter the App ID and App Secret when prompted. The secret input is hidden. Complete the Facebook login and permission approval in your browser. The command exchanges the authorization code for a user token, requests a long-lived token, and verifies ads_read and ad account access before saving it.

  4. Configure your MCP client to use the latest published version:

    {
      "mcpServers": {
        "flin-meta-ads-mcp": {
          "command": "uvx",
          "args": ["--refresh", "flin-meta-ads-mcp@latest"]
        }
      }
    }

    Call list_ad_accounts. It loads the saved login automatically, including when the server was already running without credentials. Remove any old META_ACCESS_TOKEN from its configuration and restart the MCP client after changing that configuration: an explicitly configured token takes precedence over the saved login.

The token and App Secret are stored in ~/.config/flin-meta-ads-mcp/credentials.json, with owner-only file permissions on macOS/Linux. This is a local secret file, not an encrypted keychain. Keep it out of source control. Set META_AUTH_FILE in both the login shell and the MCP configuration to use another location. Both processes must run as the same OS user or have access to the same credentials file. Delete that file to remove the local login; revoke the app in Meta to invalidate its remote access.

For Facebook Login for Business, set META_LOGIN_CONFIG_ID to a configuration that issues user access tokens and grants ads_read. The configuration controls permissions instead of the login URL's scope. This flow does not support business integration system user token configurations.

If the browser does not open, follow the printed link. Use --no-browser to only print the link, --timeout 300 to allow more time, or --redirect-uri to change the local port (and match the Meta app configuration). For a registered HTTPS redirect you control:

uvx --refresh flin-meta-ads-mcp login --manual --redirect-uri https://your-domain.example/meta/callback

After Meta redirects, paste the full address from the browser into the hidden terminal prompt. The destination must preserve the authorization code and state in the URL. No callback service is hosted by this package for HTTPS.

See Meta's manual login flow and long-lived user tokens.

Manual access token

Stable (latest published PyPI release, refreshed):

{
  "mcpServers": {
    "flin-meta-ads-mcp": {
      "command": "uvx",
      "args": ["--refresh", "flin-meta-ads-mcp"],
      "env": {
        "META_ACCESS_TOKEN": "EAA...",
        "META_GRAPH_API_VERSION": "v21.0"
      }
    }
  }
}

Latest GitHub code (main branch, refreshed):

{
  "mcpServers": {
    "flin-meta-ads-mcp": {
      "command": "uvx",
      "args": [
        "--refresh",
        "--from",
        "git+https://github.com/flin-agency/flin-meta-ads-mcp.git",
        "flin-meta-ads-mcp"
      ],
      "env": {
        "META_ACCESS_TOKEN": "EAA...",
        "META_GRAPH_API_VERSION": "v21.0"
      }
    }
  }
}

Environment variables

Authentication (choose one):

  • Run flin-meta-ads-mcp login once to save a browser login, or

  • Set META_ACCESS_TOKEN to a Meta access token with read permissions

Optional:

  • META_APP_ID: App ID for browser login (otherwise prompted)

  • META_LOGIN_CONFIG_ID: optional Facebook Login for Business user-token configuration

  • META_REDIRECT_URI: browser login callback, default http://localhost:8765/callback

  • META_AUTH_FILE: override the saved credentials path; set consistently for login and server

  • META_APP_SECRET: App Secret (App-Geheimcode) of the app that issued the access token; enables automatic appsecret_proof signing

  • META_GRAPH_API_VERSION: Graph API version, default v21.0

  • META_TIMEOUT_SECONDS: request timeout, default 30

  • META_MAX_RETRIES: retry count for transient failures, default 3

  • META_DEFAULT_AD_ACCOUNT_ID: optional fallback ad account (e.g. act_123...) used when a tool call omits ad_account_id

  • RUN_LIVE_META_TESTS: set to 1 to enable live integration tests

Ad account selection:

  • If the token has exactly one accessible ad account, the server resolves it automatically.

  • If META_DEFAULT_AD_ACCOUNT_ID is set, the server uses it when ad_account_id is omitted.

  • If the token has multiple accessible ad accounts, pass ad_account_id in the tool call.

App Secret (App-Geheimcode)

If your Meta app requires App Secret Proof, add META_APP_SECRET alongside the access token in your MCP server's env configuration:

"env": {
  "META_ACCESS_TOKEN": "EAA...",
  "META_APP_SECRET": "YOUR_APP_SECRET",
  "META_GRAPH_API_VERSION": "v21.0"
}

Find the App Secret in your Meta app dashboard under App settings > Basic. Use a user or system user access token issued for the same app, with ads_read and access to the relevant ad accounts. The App Secret alone cannot replace the access token.

The server computes an HMAC-SHA256 appsecret_proof for every Graph API request, following Meta's Business SDK. The raw App Secret is not sent in requests. Omitting META_APP_SECRET (or leaving it empty) keeps token-only authentication. Restart the MCP client after changing the configuration. Environment variables must be supplied by the MCP client or shell; the server does not automatically load .env files.

2-minute smoke test

Use these first three tool calls to confirm the server is working:

  1. list_ad_accounts

  2. list_campaigns

  3. get_insights with level=campaign and date_preset=last_7d

Example flow in Claude:

Call list_ad_accounts
Call list_campaigns
Call get_insights with level=campaign and date_preset=last_7d

If the first call works but later calls fail, the issue is usually permissions or ad account scope.

If list_campaigns returns a selection request, call it again with one of the suggested ad_account_id values.

Troubleshooting

Problem

Likely cause

Fix

Login missing

No saved login or META_ACCESS_TOKEN

Run flin-meta-ads-mcp login, then restart the MCP client

Login expired

Saved user token expired or was revoked

Run login again and restart the MCP client

Redirect rejected

Redirect does not match the Meta app settings, or HTTPS is required

Match the URI exactly; use a registered HTTPS URI with --manual for live apps

Token invalid

Expired or wrong token

Generate a valid Meta read token

Missing or invalid appsecret_proof

App requires a proof, or secret and token belong to different apps

Set META_APP_SECRET to the secret of the app that issued the token, then restart the MCP client

Permission denied

Missing ads_read or account access

Grant the token access to the ad account

Ambiguous ad account

Token can access multiple ad accounts

Pass ad_account_id per tool call

Rate limit errors

Meta API throttling

Retry later or reduce the number of insight calls

Development

Local development quickstart:

python -m pip install -e ".[dev]"
pytest -q
ruff check .
mypy src

If you want to run live Meta API tests:

RUN_LIVE_META_TESTS=1 pytest -q

Release

Keep pyproject.toml and packaging/manifest.json equal and push a matching vX.Y.Z tag. The single Release workflow runs tests and builds the Apple Silicon bundle, publishes PyPI, verifies the real PyPI updater and launch, then publishes the MCPB and checksums. Each release includes the versioned filename plus the identical flin-meta-ads-mcp.mcpb alias. Never complete a failed release with only an MCPB. README download links must point to an already published asset.

Checks distinguish Linux tests, native Apple Silicon package startup outside the source tree, and real customer-account access. Automated tests use synthetic credentials and do not establish live Meta account access. See release validation for the required evidence.

Notes

  • Use only ad accounts you are allowed to access

  • This server is intended for analysis and reporting, not mutation

  • Treat access tokens, App Secrets and the saved credentials file as secrets; use the hidden login prompt or environment variables, never chat messages or source code

Available Tools

18 tools
connection_statusA

Show the running server version and local setup without network access. Set check_live=true for one read-only Meta account access check. Never returns secrets or account data; never starts login.

Inputs: check_live.

download_ad_imageA

Download a Meta CDN image URL returned by list_ad_images, get_ad_image, or get_ad_creative. Returns the actual image file as an embedded binary resource and a direct image preview, without requiring the client to fetch the external URL. Supports JPEG, PNG, GIF, WebP up to 5 MiB. Use a fresh URL if expired.

Inputs: url (required).

get_adB

Fetch a single ad by id

Inputs: id (required), fields.

get_ad_accountB

Fetch a single ad account by id

Inputs: id (required), fields.

get_ad_creativeA

Fetch a single ad creative by id

Inputs: id (required), fields.

get_ad_imageC

Fetch a single ad image by id

Inputs: id (required), fields.

get_ad_previewB

Fetch or generate a rendered preview for an ad or ad creative

Inputs: ad_id, creative, ad_format, ad_account_id, +1 more.

get_adsetB

Fetch a single ad set by id

Inputs: id (required), fields.

get_campaignB

Fetch a single campaign by id

Inputs: id (required), fields.

get_insightsA

Fetch insights for an account, campaign, ad set, or ad

Inputs: level (required), limit, fields, breakdowns, +6 more.

get_meta_auth_statusA

Check whether Meta login is needed or has completed. Never returns tokens or secrets.

Inputs: no named parameters.

list_ad_accountsC

List ad accounts accessible by the token

Inputs: after, limit, fields, ad_account_id, +1 more.

list_ad_creativesC

List ad creatives for an ad account

Inputs: after, limit, fields, ad_account_id, +1 more.

list_ad_imagesB

List ad images for an ad account

Inputs: after, limit, fields, ad_account_id, +1 more.

list_adsC

List ads for an ad account

Inputs: after, limit, fields, ad_account_id, +1 more.

list_adsetsC

List ad sets for an ad account

Inputs: after, limit, fields, ad_account_id, +1 more.

list_campaignsC

List campaigns for an ad account

Inputs: after, limit, fields, ad_account_id, +1 more.

start_meta_loginA

Start Meta browser login when the user wants to sign in. Returns a login URL. Requires META_APP_SECRET in server configuration; app_id is public and optional if META_APP_ID is configured. After browser approval call get_meta_auth_status.

Inputs: app_id.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 18 tools

    Disambiguation4/5

    Each resource (account, campaign, adset, ad, image, creative) has a clear list_/get_ pair, and the auth/insight tools are distinct. Minor potential confusion between get_ad_preview and download_ad_image, but descriptions clarify the boundary (rendered preview vs. binary file download).

    Naming Consistency5/5

    Consistent snake_case verb_noun pattern throughout (list_campaigns, get_ad, download_ad_image, get_insights). The two status tools (connection_status, get_meta_auth_status) are slight noun-form deviations but remain readable and predictable.

    Tool Count4/5

    18 tools is slightly heavy but each maps to a distinct resource or lifecycle step in the Meta Ads domain. The list/get pairs across six resources justify the count without obvious redundancy.

    Completeness3/5

    The surface is entirely read-only: no create/update/pause/delete operations for campaigns, adsets, ads, or creatives, which are core to ad management. Insights and previews are covered, but an agent cannot perform write workflows, a notable gap for an ads server.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Read-only MCP server for Google Ads, enabling querying campaigns, ad groups, ads, insights, and keywords without create/update/delete operations.
      17
      166 PyPI
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Meta/Facebook Marketing API allowing you to view and manage ad accounts, campaigns, ad sets, ads, and creatives, as well as fetch insights and upload ad images.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      A read-only MCP server that provides comprehensive access to the TikTok Business API for retrieving advertising data, including campaigns, ad groups, ads, and performance reports.
      24
      36 PyPI
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      MCP server for the Meta Marketing API enabling ad performance reports and operational adjustments like pause/resume and budget changes on client ad accounts, with strict allowlist and read-only safeguards.
      -