Skip to main content
Glama
Social MCP

Social MCP

by abdulhadi-98

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.

License: MIT Python 3.11+ MCP

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. stdio for 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 (confirm=false). The agent must show you the preview and call again with confirm=true only after you approve.

Read-only by default

All writes are blocked until you set ALLOW_WRITES=true.

Budget cap

MAX_DAILY_BUDGET rejects any daily budget above your limit.

Account allowlists

ALLOWED_GOOGLE_ADS_CUSTOMERS and ALLOWED_META_AD_ACCOUNTS restrict which accounts can be touched.

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 audit_log.jsonl, with a timestamp and the result.

Authenticated HTTP

The remote server refuses to start without MCP_API_KEY and compares keys in constant time.

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 stdio

Getting credentials

Google Ads and GA4 (one login covers both)

  1. Create a Google Cloud project in the Cloud Console. Then enable:

    • Google Ads API

    • Google Analytics Data API

    • Google Analytics Admin API

  2. Configure the OAuth consent screen under APIs & Services → OAuth consent screen, and add yourself as a test user.

  3. Create an OAuth client ID of type Desktop app under APIs & Services → Credentials, and download the JSON file.

  4. 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.json

    While 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.

  5. 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.

  6. If you access your accounts through an MCC, set GOOGLE_ADS_LOGIN_CUSTOMER_ID to its ID.

Meta (Facebook and Instagram) Ads

  1. Create an app at developers.facebook.com (type Business) and add the Marketing API product.

  2. In Business Settings → Users → System users, create an Admin system user. Assign it your ad accounts, plus your Pages if it will create ads.

  3. Click Generate token, select your app, and grant ads_management, ads_read and business_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

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET

Google

The OAuth client from the steps above

GOOGLE_REFRESH_TOKEN

Google

Output of get_google_refresh_token.py

GOOGLE_ADS_DEVELOPER_TOKEN

Google Ads

Developer token from the API Center

GOOGLE_ADS_LOGIN_CUSTOMER_ID

Optional

MCC ID (digits only) when you access accounts through a manager

META_ACCESS_TOKEN

Meta

System user access token

META_ADLIB_TOKEN

Meta

Optional token for meta_search_ad_library; falls back to META_ACCESS_TOKEN

META_API_VERSION

Optional

Graph API version (default v24.0)

ALLOW_WRITES

Optional

true to allow confirmed changes (default false)

MAX_DAILY_BUDGET

Optional

Maximum daily budget an agent can set (default 500)

ALLOWED_GOOGLE_ADS_CUSTOMERS

Optional

Comma-separated customer IDs the server may touch

ALLOWED_META_AD_ACCOUNTS

Optional

Comma-separated ad account IDs, e.g. act_123,act_456

AUDIT_LOG_PATH

Optional

Where write actions are logged (default audit_log.jsonl)

MCP_API_KEY

HTTP mode

Secret that clients must send to the remote server

HOST / PORT

Optional

HTTP bind address (default 0.0.0.0:8000)

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-mcp

Cursor 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_KEY

The 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_KEY

Deploying 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-mcp

To 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 http

Tool reference

Google Ads

Tool

Type

Description

google_ads_list_accounts

Read

All accessible accounts, with name, currency and manager flag

google_ads_list_client_accounts

Read

Client accounts under an MCC

google_ads_query

Read

Run any GAQL query

google_ads_campaign_performance

Read

Spend, clicks, conversions, CPA and ROAS per campaign

google_ads_set_status

Write

Pause or enable a campaign, ad group, ad or keyword

google_ads_set_campaign_budget

Write

Change a campaign's daily budget (warns about shared budgets)

google_ads_set_ad_group_cpc_bid

Write

Set an ad group's max CPC

google_ads_add_negative_keywords

Write

Add campaign-level negative keywords

Google Analytics 4

Tool

Type

Description

ga4_list_properties

Read

All accounts and properties

ga4_run_report

Read

Metrics and dimensions with date ranges, filters and sorting

ga4_realtime_report

Read

Users active in the last 30 minutes

ga4_get_metadata

Read

Search the available dimensions and metrics

ga4_create_key_event

Write

Mark an event as a key event (conversion)

ga4_create_custom_dimension

Write

Register an event or user parameter as a custom dimension

Meta Ads

Tool

Type

Description

meta_list_ad_accounts

Read

All accessible ad accounts

meta_list_entities

Read

Campaigns, ad sets or ads, with status and budgets

meta_get_insights

Read

Performance with breakdowns and daily rows

meta_search_ad_library

Read

Search the public Meta Ad Library for any advertiser's ads (competitor research)

meta_set_status

Write

Pause or activate a campaign, ad set or ad

meta_set_budget

Write

Change a daily or lifetime budget (handles currency units)

meta_update_entity

Write

Update safe fields (name, bid, schedule, spend cap)

meta_create_campaign

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.example

Adding a tool

  1. Write a typed function with a clear docstring in the relevant platform module. The docstring becomes the tool description the AI sees.

  2. Wrap any account change in guarded_write(...) so it gets the preview, confirmation and audit behavior.

  3. Register the function in TOOLS in ads_mcp/server.py with the READ or WRITE annotation.

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

MIT © Discret Digital

Available Tools

21 tools
ga4_create_custom_dimensionB
Destructive

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_eventC
Destructive

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_metadataA
Read-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_propertiesA
Read-only

List every GA4 account and property the authenticated user can access.

Inputs: no named parameters. Returns: object

ga4_realtime_reportB
Read-only

Users active in the last 30 minutes. Defaults to activeUsers by country.

Inputs: property_id (required), metrics, dimensions. Returns: object

ga4_run_reportB
Read-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

meta_create_campaignA
Destructive

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_insightsB
Read-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_accountsB
Read-only

List every Meta ad account the token can access (including via Business Managers).

Inputs: limit. Returns: object

meta_list_entitiesA
Read-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_budgetC
Destructive

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_statusC
Destructive

Pause or activate a Meta campaign, ad set or ad by id.

Inputs: status (required), object_id (required), confirm. Returns: object

meta_update_entityB
Destructive

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

    B3.2/5.0

    Scored across 21 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to manage, report, and analyze Google Ads campaigns securely with encrypted multi-client support, real-time API integrations, and audit trail logging.
      -
    • A
      license
      Not graded
      quality
      F
      maintenance
      Connects Google Ads, Meta Ads, and LinkedIn Ads to AI assistants, enabling natural language ad campaign management, reporting, and optimization across platforms.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Connects 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
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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