flin-meta-ads-mcp
This server provides read-only Meta Ads analysis and browser-login/status tooling through Claude.
List and fetch accessible Meta ad accounts.
List and read campaigns, ad sets, ads, ad images, and ad creatives.
Fetch ad previews, including
preview_urllinks.Retrieve insights at account, campaign, ad set, and ad levels with date presets, time ranges, breakdowns, and pagination/limits.
Download Meta CDN ad images as MCP embedded binary resources and image previews (JPEG, PNG, GIF, WebP up to 5 MiB).
Check local/live connection status and Meta authentication status.
Start Meta browser login when configured, without exposing tokens or secrets.
Stay strictly read-only: no create, update, pause, resume, delete, or generic Graph API proxy actions.
Provides read-only access to Meta Ads accounts, campaigns, ad sets, ads, ad images, creatives, ad previews, and insights for analysis and reporting.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@flin-meta-ads-mcp show campaign insights for last 7 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Download the
.mcpb, then open Claude Settings → Extensions → Advanced settings → Install Extension… (Extensions may be under Desktop app).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.For browser login, call
start_meta_login, open its login link and approve access with your Facebook/Meta account. The administrator must allowhttp://localhost:8765/callbackin the Meta app. An existing token skips login.Call
connection_status, thenconnection_statuswithcheck_live=trueto verify Meta access (server 0.1.17 or newer). The default call is local only:auth_status=unknownwith a token is expected until a live check. On older servers, useget_meta_auth_status, thenlist_ad_accountsfor a real check.Call
list_ad_accounts, select the intended account, thenlist_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_imageGets ad previews (including
preview_urllinks)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-mcpInstall and refresh to the newest published release:
uvx --refresh flin-meta-ads-mcpRun the latest GitHub code (main branch):
uvx --refresh --from git+https://github.com/flin-agency/flin-meta-ads-mcp.git flin-meta-ads-mcpManual 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.
In your Meta app, enable Facebook Login (or Facebook Login for Business) and the
ads_readpermission. Copy the App ID and App Secret / App-Geheimcode from App settings > Basic.Configure the OAuth redirect to match
http://localhost:8765/callbackfor local development. Meta's localhost HTTP exception is for development apps; use a registered HTTPS redirect with--manualif your app requires HTTPS. Development apps require the signing-in user to have an app role. Public use may require App Review.Start the login:
uvx --refresh flin-meta-ads-mcp loginEnter 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_readand ad account access before saving it.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 oldMETA_ACCESS_TOKENfrom 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/callbackAfter 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 loginonce to save a browser login, orSet
META_ACCESS_TOKENto 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 configurationMETA_REDIRECT_URI: browser login callback, defaulthttp://localhost:8765/callbackMETA_AUTH_FILE: override the saved credentials path; set consistently for login and serverMETA_APP_SECRET: App Secret (App-Geheimcode) of the app that issued the access token; enables automaticappsecret_proofsigningMETA_GRAPH_API_VERSION: Graph API version, defaultv21.0META_TIMEOUT_SECONDS: request timeout, default30META_MAX_RETRIES: retry count for transient failures, default3META_DEFAULT_AD_ACCOUNT_ID: optional fallback ad account (e.g.act_123...) used when a tool call omitsad_account_idRUN_LIVE_META_TESTS: set to1to 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_IDis set, the server uses it whenad_account_idis omitted.If the token has multiple accessible ad accounts, pass
ad_account_idin 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:
list_ad_accountslist_campaignsget_insightswithlevel=campaignanddate_preset=last_7d
Example flow in Claude:
Call list_ad_accounts
Call list_campaigns
Call get_insights with level=campaign and date_preset=last_7dIf 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 | Run |
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 |
Token invalid | Expired or wrong token | Generate a valid Meta read token |
Missing or invalid | App requires a proof, or secret and token belong to different apps | Set |
Permission denied | Missing | Grant the token access to the ad account |
Ambiguous ad account | Token can access multiple ad accounts | Pass |
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 srcIf you want to run live Meta API tests:
RUN_LIVE_META_TESTS=1 pytest -qRelease
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 toolsconnection_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
Scored across 18 tools
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).
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.
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.
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
Related MCP Connectors
Meta Ads MCP server: run Facebook and Instagram campaigns, ad sets, ads and reports from AI.
Read-only MCP connector for Adlane workspaces, Google and Meta ad accounts and campaign reports.
Meta Ads MCP: Facebook and Instagram reports, campaigns, creatives, audiences. Approval on writes.
Meta Ads MCP: read ad accounts and signal health; propose governed changes under Ask or Full.
Related MCP Servers
- AlicenseCqualityBmaintenanceRead-only MCP server for Google Ads, enabling querying campaigns, ad groups, ads, insights, and keywords without create/update/delete operations.17166 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceMCP 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
- AlicenseBqualityCmaintenanceA 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.2436 PyPIMIT
- FlicenseNot gradedqualityBmaintenanceMCP 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.-