Social MCP
Social MCP lets AI agents read and manage Google Ads, Google Analytics 4, and Meta Ads accounts through an MCP server.
Google Ads: list accessible/MCC accounts, run any GAQL query, pull campaign performance with CPA/ROAS, pause/enable entities, change daily budgets, set ad group CPC bids, and add negative keywords.
Google Analytics 4: list properties, run reports with dimensions/metrics/filters/sorting, get realtime data and metadata, create key events, and register custom dimensions.
Meta Ads: list ad accounts and campaigns/ad sets/ads, get insights with breakdowns and daily rows, search the public Ad Library, pause/activate entities, set budgets, update safe fields, and create always-paused campaigns.
Safety controls: preview-confirm write flow, read-only by default, budget caps, account allowlists, audit logging, and authenticated HTTP mode.
Deployment/client options: works over stdio for local clients and Streamable HTTP for remote/web clients; Docker-ready and compatible with MCP clients such as Claude, Cursor, Grok, OpenAI Agents SDK, LangChain, and n8n.
Provides tools for managing Google Ads accounts, including listing accessible and MCC client accounts, running GAQL queries, retrieving campaign performance with CPA and ROAS, pausing or enabling campaigns/ad groups/ads/keywords, changing daily budgets and ad group CPC bids, and adding negative keywords.
Provides tools for working with Google Analytics 4 properties, including listing accounts and properties, running reports with metrics, dimensions, date ranges, filters and sorting, accessing realtime reports, looking up metadata, and marking key events.
Provides tools for managing Meta Ads accounts, including retrieving insights with breakdowns, creating paused campaigns with daily budgets, and performing limited safe-field updates on Meta ad entities.
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., "@Social MCP Which Google Ads campaigns had a CPA above $40 last week, and pause the worst one?"
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.
Social MCP
Let your AI agent run your ads and read your analytics: Google Ads, Google Analytics 4 and Meta Ads, in one MCP server.
Built and maintained by Discret Digital
Social MCP is an open-source Model Context Protocol server. It connects AI assistants and agents to your advertising and analytics accounts. Once connected, you can ask in plain language:
"Which Google Ads campaigns had a CPA above $40 last week? Pause the worst one."
"Compare Meta and Google spend against GA4 conversions by source / medium for the last 30 days."
"Pull the search terms for my brand campaign and add the irrelevant ones as negatives."
"Create a paused Meta sales campaign called 'Black Friday' with a $100/day budget."
It works with any MCP-compatible client: Claude (Desktop, Code and web), Grok through the xAI API, Cursor, the OpenAI Agents SDK, LangChain, n8n and others.
Contents
Related MCP server: PaidSync MCP Server
Features
Multi-account by default. It works with every Google Ads account (including manager/MCC client accounts), every GA4 property and every Meta ad account your credentials can access.
Read and write. Agents can report, analyse and act: pause, enable, change budgets and bids, add negative keywords, create campaigns, and mark GA4 key events.
Built-in reporting helpers. You can run any Google Ads Query Language (GAQL) query, or use ready-made campaign performance reports with CPA and ROAS. Meta insights support breakdowns, and GA4 reports support filters, realtime data and metadata lookup.
Two transports.
stdiofor local clients, and Streamable HTTP for remote and web clients.Docker-ready. A single container can be deployed to Cloud Run, Railway, Render, Fly.io or any VPS.
Safety by design
Ad accounts spend real money, so every change goes through several layers of protection:
Guardrail | What it does |
Preview → confirm | Every write tool returns a dry-run preview by default ( |
Read-only by default | All writes are blocked until you set |
Budget cap |
|
Account allowlists |
|
Paused creation | New Meta campaigns are always created PAUSED. |
Field allowlist | Generic Meta updates are limited to a fixed set of safe fields. |
Audit log | Every executed write is appended to |
Authenticated HTTP | The remote server refuses to start without |
Quick start
git clone https://github.com/abdulhadi-98/Social-Mcp.git
cd Social-Mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env # fill in your credentials (see below)
social-mcp # runs over stdioGetting credentials
Google Ads and GA4 (one login covers both)
Create a Google Cloud project in the Cloud Console. Then enable:
Google Ads API
Google Analytics Data API
Google Analytics Admin API
Configure the OAuth consent screen under APIs & Services → OAuth consent screen, and add yourself as a test user.
Create an OAuth client ID of type Desktop app under APIs & Services → Credentials, and download the JSON file.
Generate a refresh token. A browser window opens; sign in with the Google account that can access your Ads and GA4 accounts.
python scripts/get_google_refresh_token.py path/to/client_secret.jsonWhile the consent screen is in Testing mode, refresh tokens expire after 7 days. Publish the app to get a long-lived token. It can stay unverified for personal or internal use.
Get a Google Ads developer token from a manager (MCC) account under Tools → API Center. New tokens have Test access, which only works with test accounts. Apply for Basic access to manage live accounts.
If you access your accounts through an MCC, set
GOOGLE_ADS_LOGIN_CUSTOMER_IDto its ID.
Meta (Facebook and Instagram) Ads
Create an app at developers.facebook.com (type Business) and add the Marketing API product.
In Business Settings → Users → System users, create an Admin system user. Assign it your ad accounts, plus your Pages if it will create ads.
Click Generate token, select your app, and grant
ads_management,ads_readandbusiness_management. System user tokens do not expire.
Configuration
All settings come from environment variables or a .env file in the project root. See .env.example.
Variable | Required | Description |
| The OAuth client from the steps above | |
| Output of | |
| Google Ads | Developer token from the API Center |
| Optional | MCC ID (digits only) when you access accounts through a manager |
| Meta | System user access token |
| Meta | Optional token for |
| Optional | Graph API version (default |
| Optional |
|
| Optional | Maximum daily budget an agent can set (default |
| Optional | Comma-separated customer IDs the server may touch |
| Optional | Comma-separated ad account IDs, e.g. |
| Optional | Where write actions are logged (default |
| HTTP mode | Secret that clients must send to the remote server |
| Optional | HTTP bind address (default |
You only need credentials for the platforms you use. Tools for an unconfigured platform return a clear error.
Connecting your AI client
Local clients (stdio)
Claude Desktop: add this to claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"social-mcp": { "command": "/absolute/path/to/Social-Mcp/.venv/bin/social-mcp" }
}
}Claude Code:
claude mcp add social-mcp -- /absolute/path/to/Social-Mcp/.venv/bin/social-mcpCursor and other stdio clients: use the same command, /absolute/path/to/Social-Mcp/.venv/bin/social-mcp.
Remote clients (HTTP)
First deploy the server (see Deploying as a remote server). Your endpoint is https://YOUR-HOST/mcp.
Claude web and mobile: go to Settings → Connectors → Add custom connector and enter:
https://YOUR-HOST/mcp?key=YOUR_MCP_API_KEYThe key is passed in the URL because that form only accepts a URL. Treat the full URL like a password.
Grok (xAI API): pass the server as a remote MCP tool. See scripts/grok_example.py for a full example:
tools=[{
"type": "mcp",
"server_label": "social-mcp",
"server_url": "https://YOUR-HOST/mcp",
"authorization": "YOUR_MCP_API_KEY",
}]Check the xAI docs for the current remote-MCP field names.
Claude Code (remote), the OpenAI Agents SDK, LangChain, n8n and others: connect to https://YOUR-HOST/mcp with this header:
Authorization: Bearer YOUR_MCP_API_KEYDeploying as a remote server
# Generate an API key
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Build and run
docker build -t social-mcp .
docker run -p 8000:8000 --env-file .env social-mcpTo check that it's running, open GET /health. It returns {"ok": true, "writes_enabled": false}.
On a managed platform (Cloud Run, Railway, Render, Fly.io), set your variables as the platform's secrets rather than baking .env into the image. Always serve the server over HTTPS.
To run it without Docker:
social-mcp --transport httpTool reference
Google Ads
Tool | Type | Description |
| Read | All accessible accounts, with name, currency and manager flag |
| Read | Client accounts under an MCC |
| Read | Run any GAQL query |
| Read | Spend, clicks, conversions, CPA and ROAS per campaign |
| Write | Pause or enable a campaign, ad group, ad or keyword |
| Write | Change a campaign's daily budget (warns about shared budgets) |
| Write | Set an ad group's max CPC |
| Write | Add campaign-level negative keywords |
Google Analytics 4
Tool | Type | Description |
| Read | All accounts and properties |
| Read | Metrics and dimensions with date ranges, filters and sorting |
| Read | Users active in the last 30 minutes |
| Read | Search the available dimensions and metrics |
| Write | Mark an event as a key event (conversion) |
| Write | Register an event or user parameter as a custom dimension |
Meta Ads
Tool | Type | Description |
| Read | All accessible ad accounts |
| Read | Campaigns, ad sets or ads, with status and budgets |
| Read | Performance with breakdowns and daily rows |
| Read | Search the public Meta Ad Library for any advertiser's ads (competitor research) |
| Write | Pause or activate a campaign, ad set or ad |
| Write | Change a daily or lifetime budget (handles currency units) |
| Write | Update safe fields (name, bid, schedule, spend cap) |
| Write | Create a campaign, always paused |
Project structure
Social-Mcp/
├── ads_mcp/
│ ├── server.py # MCP server, tool registry, HTTP auth
│ ├── google_ads.py # Google Ads tools
│ ├── ga4.py # Google Analytics 4 tools
│ ├── meta_ads.py # Meta Marketing API tools
│ ├── safety.py # Preview/confirm, limits, allowlists, audit log
│ └── config.py # Environment settings
├── scripts/
│ ├── get_google_refresh_token.py
│ └── grok_example.py
├── Dockerfile
├── pyproject.toml
└── .env.exampleAdding a tool
Write a typed function with a clear docstring in the relevant platform module. The docstring becomes the tool description the AI sees.
Wrap any account change in
guarded_write(...)so it gets the preview, confirmation and audit behavior.Register the function in
TOOLSinads_mcp/server.pywith theREADorWRITEannotation.
Roadmap
Google Ads campaign, ad group and responsive search ad creation
Meta ad set and ad creation, plus creative upload
TikTok Ads and LinkedIn Ads
OAuth 2.1 sign-in for the remote server
Search Console and Merchant Center
Contributing
Contributions are welcome. Open an issue to discuss larger changes, or send a pull request for fixes and new tools. Please keep new write tools behind guarded_write.
Security
Never commit .env, OAuth client files or access tokens; they are already in .gitignore. If you find a security issue, please report it privately through discretdigital.com instead of opening a public issue.
Disclaimer
Social MCP is not affiliated with, endorsed by or sponsored by Google or Meta. "Google Ads" and "Google Analytics" are trademarks of Google LLC. "Meta", "Facebook" and "Instagram" are trademarks of Meta Platforms, Inc. You are responsible for every change made to your ad accounts, so review the previews before you approve them.
License
Available Tools
21 toolsga4_create_custom_dimensionBDestructive
Register an event or user parameter as a custom dimension so it can be used in reports.
Inputs: property_id (required), display_name (required), parameter_name (required), scope, +2 more. Returns: object
ga4_create_key_eventCDestructive
Mark an event (e.g. "generate_lead", "purchase") as a key event (conversion) in GA4.
Inputs: event_name (required), property_id (required), confirm. Returns: object
ga4_get_metadataARead-only
List the dimension and metric API names available for a property (optionally filtered by a search term).
Inputs: property_id (required), search. Returns: object
ga4_list_propertiesARead-only
List every GA4 account and property the authenticated user can access.
Inputs: no named parameters. Returns: object
ga4_realtime_reportBRead-only
Users active in the last 30 minutes. Defaults to activeUsers by country.
Inputs: property_id (required), metrics, dimensions. Returns: object
ga4_run_reportBRead-only
Run a GA4 report.
metrics e.g. ["sessions", "totalUsers", "conversions", "purchaseRevenue"]; dimensions e.g. ["date", "sessionSourceMedium", "sessionCampaignName", "landingPage"]. Dates: YYYY-MM-DD, "today", "yesterday" or "NdaysAgo". dimension_filters: [{"field": "sessionSourceMedium", "value": "google / cpc", "match": "EXACT|CONTAINS|BEGINS_WITH"}] (ANDed). order_by_metric: sort descending by this metric.
Inputs: metrics (required), property_id (required), limit, end_date, +4 more. Returns: object
google_ads_add_negative_keywordsCDestructive
Add campaign-level negative keywords (e.g. wasteful search terms found in a search-term report).
Inputs: keywords (required), campaign_id (required), customer_id (required), confirm, +2 more. Returns: object
google_ads_campaign_performanceBRead-only
Campaign-level spend, clicks, impressions, conversions, CPA and ROAS for a date range.
date_range is a GAQL predefined range, e.g. TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH.
Inputs: customer_id (required), date_range, include_paused, login_customer_id. Returns: object
google_ads_list_accountsCRead-only
List every Google Ads account the authenticated user can access, with name, currency and whether it is a manager (MCC).
Inputs: login_customer_id. Returns: object
google_ads_list_client_accountsCRead-only
List the client accounts under a manager (MCC) account.
Inputs: manager_customer_id (required). Returns: object
google_ads_queryBRead-only
Run any read-only Google Ads Query Language (GAQL) query.
Example: SELECT campaign.id, campaign.name, metrics.clicks, metrics.cost_micros FROM campaign WHERE segments.date DURING LAST_7_DAYS Costs are in micros (divide by 1,000,000).
Inputs: gaql (required), customer_id (required), limit, login_customer_id. Returns: object
google_ads_set_ad_group_cpc_bidBDestructive
Set an ad group's max CPC bid (account currency). Only applies to manual CPC bidding.
Inputs: cpc_bid (required), ad_group_id (required), customer_id (required), confirm, +1 more. Returns: object
google_ads_set_campaign_budgetCDestructive
Change a campaign's daily budget (in the account currency, e.g. 50 = $50/day).
Inputs: campaign_id (required), customer_id (required), daily_budget (required), confirm, +1 more. Returns: object
google_ads_set_statusCDestructive
Pause or enable a campaign, ad group, ad or keyword.
entity_id: the campaign/ad group id; for ads and keywords use "<ad_group_id>~<ad_id or criterion_id>".
Inputs: level (required), status (required), entity_id (required), customer_id (required), +2 more. Returns: object
meta_create_campaignADestructive
Create a new campaign. It is always created PAUSED so nothing spends until you activate it.
daily_budget (major units) enables campaign budget optimization; omit it to set budgets on ad sets instead. special_ad_categories: [] or e.g. ["HOUSING"], ["EMPLOYMENT"], ["FINANCIAL_PRODUCTS_SERVICES"].
Inputs: name (required), objective (required), ad_account_id (required), confirm, +2 more. Returns: object
meta_get_insightsBRead-only
Performance insights for an ad account (act_...), campaign, ad set or ad.
date_preset: today, yesterday, last_7d, last_14d, last_30d, this_month, last_month, maximum (ignored if since/until given). breakdowns e.g. ["age","gender"], ["publisher_platform"], ["country"]. time_increment "1" for daily rows.
Inputs: object_id (required), level, limit, since, +5 more. Returns: object
meta_list_ad_accountsBRead-only
List every Meta ad account the token can access (including via Business Managers).
Inputs: limit. Returns: object
meta_list_entitiesARead-only
List campaigns, ad sets or ads in an ad account with their status and budgets.
effective_status filter e.g. ["ACTIVE"] or ["ACTIVE","PAUSED"]. Budgets are returned in minor units (cents).
Inputs: ad_account_id (required), limit, entity_type, effective_status. Returns: object
meta_set_budgetCDestructive
Change the budget of a campaign (CBO) or ad set, in the account currency's major units (e.g. 50 = $50).
Inputs: amount (required), object_id (required), confirm, budget_type. Returns: object
meta_set_statusCDestructive
Pause or activate a Meta campaign, ad set or ad by id.
Inputs: status (required), object_id (required), confirm. Returns: object
meta_update_entityBDestructive
Update allowed fields (name, status, bid_amount, start_time, end_time, spend_cap, budgets) on a campaign, ad set or ad.
Budget, bid and spend_cap values must be in minor units (cents), as the Marketing API expects. Prefer meta_set_budget for budgets.
Inputs: fields (required), object_id (required), confirm. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Most tools are clearly separated by platform and resource/action, with distinct prefixes like ga4_, google_ads_, and meta_. Some boundaries blur between generic and specialized tools, especially google_ads_query vs google_ads_campaign_performance, and meta_update_entity vs meta_set_status/meta_set_budget.
Names consistently use snake_case with platform prefixes (ga4_, google_ads_, meta_), making the set easy to scan. Minor deviations exist, such as google_ads_campaign_performance being noun-phrase rather than verb_noun, and meta_list_entities being somewhat generic.
21 tools is slightly high in isolation, but reasonable for a server spanning three platforms: GA4, Google Ads, and Meta Ads. Each platform has a focused subset, though the set is near the upper end of what an agent can comfortably navigate.
The surface covers reporting, status changes, budgets, and some creation operations, but lifecycle coverage is uneven. Google Ads lacks creation tools for campaigns/ad groups/ads/keywords, and Meta only supports creating campaigns rather than ad sets or ads, creating notable gaps for full ad management.
Related MCP Connectors
Manage Google, Meta, TikTok, Snapchat and LinkedIn ads, plus GA4, Tag Manager and Search Console, by chat from Claude or ChatGPT. Spend increases need your confirmation first.
AI marketing agent for Google Ads, Meta, GA4, TikTok, LinkedIn, Shopify, HubSpot and more.
Connect authorized ad accounts to AI assistants for audits, reporting, and approval-gated changes.
Run Google Ads and Meta Ads from ChatGPT or Claude: audit wasted spend, create and manage campaigns.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage, report, and analyze Google Ads campaigns securely with encrypted multi-client support, real-time API integrations, and audit trail logging.-

PaidSync MCP Serverofficial
AlicenseNot gradedqualityFmaintenanceConnects Google Ads, Meta Ads, and LinkedIn Ads to AI assistants, enabling natural language ad campaign management, reporting, and optimization across platforms.MIT- FlicenseNot gradedqualityCmaintenanceConnects AI assistants to Google Ads, Meta Ads, ChatGPT Ads, TikTok Ads and LinkedIn Ads so users can query live campaign performance, budgets and audiences in the account's own currency and prepare changes as proposals that only take effect after explicit approval. Reads run immediately, while every write is staged as an approvable proposal with before/after values, and newly created campaigns, ad sets and ads start paused.1-

Apogee MCP Serverofficial
AlicenseNot gradedqualityBmaintenanceEnables AI agents to bulk-launch, manage, and analyze ads across multiple Meta, TikTok, and Snapchat ad accounts, with scoped permissions and approval-gated changes.MIT