aapl-ads-mcp
The aapl-ads-mcp server connects AI assistants to the Apple Search Ads API v5, enabling read-only querying of ASA account data through natural language.
Health Check (
health) — Verify the MCP server is running without requiring ASA authentication.List Organizations (
list_orgs) — Verify credentials and discover accessible orgs, including ID, name, currency, timezone, and role.List Campaigns (
list_campaigns) — Enumerate campaigns with metadata (id, name, status, budget, country, channel type); filter by status (ENABLED, PAUSED, DELETED) and paginate.List Ad Groups (
list_ad_groups) — List ad groups within a campaign, including default bid and automated keyword opt-in settings.List Keywords (
list_keywords) — Retrieve targeting keywords for an ad group, including text, match type (BROAD/EXACT), bid amount, and status.Campaign Performance Report (
get_campaign_report) — Fetch campaign-level metrics (impressions, taps, TTR, spend, avgCPT, avgCPM, installs, CPI) with configurable date range and granularity (HOURLY/DAILY/WEEKLY/MONTHLY).Ad Group Performance Report (
get_ad_group_report) — Fetch ad group-level metrics broken down by country/region, with configurable date range and granularity.Keyword Performance Report (
get_keyword_report) — Fetch per-keyword metrics (impressions, taps, TTR, spend, CPI, installs) for a specific ad group, with configurable date range and granularity.Search Terms Report (
get_search_terms_report) — Retrieve actual user search queries that triggered ads, with performance metrics per term — ideal for keyword discovery and negative keyword identification (aggregate totals only, no granularity breakdown).
All tools default to the last 30 days, support pagination, and require ASA API credentials. No write operations are supported.
Integrates with Apple Search Ads API v5 to query campaigns, ad groups, keywords, and performance reports.
aapl-ads-mcp
An MCP server that connects Claude (and any MCP-compatible client) to Apple Search Ads API v5.
What is this
MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools. This server implements the MCP stdio transport and exposes 9 read-only tools that query your Apple Search Ads account — campaigns, ad groups, keywords, and performance reports.
You install it once, point Claude Desktop at it, and then ask questions in plain English: "Which keywords drove the most installs last month?" or "Show me campaigns with zero impressions this week."
Related MCP server: Reddit Ads MCP Server
Why
The official ASA dashboards are good for humans but not for ad-hoc analysis or automated reporting. Existing MCP alternatives are either SaaS (you hand over your keys) or unmaintained. This is a self-hosted, open-source option you control.
Features
list_orgs — verify authentication, list accessible organizations
list_campaigns — enumerate campaigns, optionally filter by status
list_ad_groups — ad groups for a given campaign
list_keywords — targeting keywords with bid amounts and match type
get_campaign_report — impressions, taps, installs, spend, CPI, TTR by campaign
get_ad_group_report — same metrics broken down by ad group
get_keyword_report — per-keyword performance with weekly/daily/monthly granularity
get_search_terms_report — the real search queries that triggered your ads (most useful for discovery)
All tools default to the last 30 days. Reports support HOURLY, DAILY,
WEEKLY, and MONTHLY granularity.
Limitations
Read-only by design. No write operations (create, update, pause) in this release.
Requires Apple Search Ads Campaign Management API access. You need to create an API user in your ASA account and generate an ES256 key pair.
Aggregate install metrics work without app-side integration.
tapInstalls,viewInstalls, and related fields in ASA reports are populated by Apple Search Ads directly and do not require any SDK in your app. AdServices / AdAttributionKitis only needed if you want to attribute installs to specific campaigns from inside your app (e.g. for onboarding personalization).Single organization. The org ID is fixed in the config. Multi-org switching is not implemented.
Setup
1. Generate an ES256 key pair
Use the modern genpkey command — it produces PKCS#8 format directly, which is what this server requires. The older ecparam -genkey produces SEC1 format and will cause a startup error.
# Generate private key (PKCS#8)
openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 -out private-key.pem
# Derive public key
openssl pkey -in private-key.pem -pubout -out public-key.pemVerify the private key starts with -----BEGIN PRIVATE KEY----- (not -----BEGIN EC PRIVATE KEY-----). If it starts with the EC variant, convert it:
openssl pkcs8 -topk8 -nocrypt -in ec-key.pem -out private-key.pemStore private-key.pem outside the repository root if possible (e.g. ~/.ssh/asa-private-key.pem).
2. Create an API user in Apple Search Ads
Go to ASA → Account Settings → User Management
Click Create User, choose role API Account Read Only for read-only usage (recommended for this server). API Campaign Manager is also fine and adds write permissions if you plan to extend the server with write tools later.
Go to the API tab, click Create Client
Upload
public-key.pemCopy
client_id,team_id, andkey_idfrom the confirmation screenFind your
org_idin Account Settings → Overview
3. Clone and build
git clone https://github.com/andrealufino/aapl-ads-mcp.git
cd aapl-ads-mcp
npm install
npm run build4. Configure Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"aapl-ads": {
"command": "node","args": ["/absolute/path/to/aapl-ads-mcp/dist/index.js"], "env": { "ASA_CLIENT_ID": "SEARCHADS.your-client-id-here",
"ASA_TEAM_ID": "SEARCHADS.your-team-id-here",
"ASA_KEY_ID": "your-key-id-here",
"ASA_ORG_ID": "12345678",
"ASA_PRIVATE_KEY_PATH": "/absolute/path/to/private-key.pem"
} }
} }
**Note:** `ASA_PRIVATE_KEY_PATH` must be an absolute path. Tilde (`~`) is not
expanded by Node.js — use the full path.
For container or cloud deployments where mounting a file is impractical, set
`ASA_PRIVATE_KEY` to the inline PEM contents instead (newlines preserved). If
both are set, `ASA_PRIVATE_KEY` wins.
Restart Claude Desktop. Ask "run health check" to verify the server is
connected.
## Usage examples
These are natural-language prompts that work with Claude Desktop once the server
is running:List my Apple Ads campaigns
Show me the last 30 days of campaign performanceWhich keywords drove installs in my Brand campaign last week?What search terms triggered my ads in the past month? Focus on ones
with impressions but no installs.Compare weekly spend across all campaigns for Q1 2025Show ad groups in campaign 1234567890 with their bid amountsDevelopment
npm run build # compile TypeScript
npm test # run test suite (Vitest)
npm run typecheck # type-check without emitting
npm run lint # Biome lint
npm run format # Biome format (write)MCP Inspector
To debug tool calls interactively without Claude Desktop:
npx @modelcontextprotocol/inspector node dist/index.jsSet the env vars in the Inspector UI before connecting.
Pre-commit hooks
Install lefthook hooks locally after cloning:
npx lefthook installThis sets up:
gitleaks protect --staged— blocks commits that contain secretsBiome lint check on staged
.tsfilesTypeScript type check
Contributing
See docs/ARCHITECTURE.md for technical details: auth
flow, HTTP client design, tool pattern, report schema quirks, and ASA v5
lessons learned during development.
Bug reports and pull requests welcome.
Security
Never commit
.envor*.pemfiles — both are in.gitignoreKeep
private-key.pemoutside the repository rootThe access token is held in memory only, never written to disk
If you suspect a key has been exposed, rotate it in ASA → Account Settings → API
License
MIT — see LICENSE.
Available Tools
9 toolsget_ad_group_reportA
Fetch performance metrics for ad groups within a specific Apple Search Ads campaign: impressions, taps, TTR, spend, CPI, installs (tap-through and view-through), and install rate. Requires ASA authentication; read-only. Use get_campaign_report for a campaign-level summary, or get_keyword_report for keyword-level detail. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.
Inputs: campaignId (required), endDate, startDate, adGroupIds, +1 more.
get_campaign_reportA
Fetch performance metrics for Apple Search Ads campaigns: impressions, taps, tap-through rate (TTR), localSpend, avgCPT, avgCPM, tapInstalls, viewInstalls, totalInstalls, new downloads, redownloads, CPI, and install rate. Requires ASA authentication; read-only. Use get_ad_group_report or get_keyword_report for deeper breakdowns. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.
Inputs: startDate, endDate, granularity, campaignIds.
get_keyword_reportA
Fetch performance metrics for targeting keywords in a specific Apple Search Ads ad group: impressions, taps, TTR, spend, CPI, installs, and install rate broken down per keyword. Requires ASA authentication; read-only. Use get_search_terms_report to see the actual user queries that triggered these keywords. Results are grouped by country/region and include grand totals. Defaults to the last 30 days with WEEKLY granularity.
Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.
get_search_terms_reportA
Fetch the actual user search queries that triggered Apple Search Ads impressions, along with performance metrics per search term. Requires ASA authentication; read-only. Most useful for keyword discovery (finding new terms to add) and negation (finding irrelevant queries to exclude). Does not support granularity breakdown — returns aggregate totals per search term. Use get_keyword_report to see metrics for your configured targeting keywords instead. Defaults to the last 30 days.
Inputs: campaignId (required), adGroupId (required), startDate, endDate, +1 more.
healthA
Check if the aapl-ads-mcp server is running and reachable. Use this to verify the MCP connection before making API calls. No ASA authentication is required — returns server name, version, and current timestamp.
Inputs: no named parameters.
list_ad_groupsA
List ad groups within a specific Apple Search Ads campaign. Requires ASA authentication; read-only. Returns ad group metadata (id, name, status, default bid, automated keyword opt-in) but not performance metrics — use get_ad_group_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.
Inputs: campaignId (required), limit, offset.
list_campaignsA
List all campaigns in the configured Apple Search Ads organization. Requires ASA authentication; read-only. Returns campaign metadata (id, name, status, budget, country, channel type) but not performance metrics — use get_campaign_report for metrics. Optionally filter by status. Supports pagination via limit/offset; default limit 20, max 1000.
Inputs: status, limit, offset.
list_keywordsA
List targeting keywords for a specific Apple Search Ads ad group. Requires ASA authentication; read-only. Returns keyword metadata (text, match type BROAD/EXACT, bid amount, status) but not performance metrics — use get_keyword_report for metrics. Supports pagination via limit/offset; default limit 20, max 1000.
Inputs: campaignId (required), adGroupId (required), limit, offset.
list_orgsA
List all Apple Search Ads organizations accessible with the configured credentials. Requires ASA authentication. Use this to verify credentials are valid and to discover available org IDs before calling other tools. Returns org ID, name, currency, timezone, payment model, and assigned role names.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct entity and action: list_* for enumerating hierarchy levels, get_*_report for metrics at each level, get_search_terms_report for search queries, and health for server status. No two tools could be confused for the same task.
Most tools follow the list_ or get_*_report pattern clearly separating metadata enumeration from report retrieval. The single deviation is 'health', which is a noun rather than a verb-prefixed action (e.g., check_health), making the pattern slightly inconsistent.
Nine tools is well-scoped for a read-only Apple Search Ads data access server: four list tools for entity hierarchy, four report tools for metrics breakdowns, and a health check. Each tool serves a distinct need without redundancy.
The read-only surface covers the full object hierarchy (org → campaign → ad group → keyword) with list operations and corresponding report endpoints, including search terms. However, the complete absence of write operations (no create/update/delete for campaigns or keywords) could be a gap if management tasks are expected, though it appears intentionally read-only.
Related MCP Connectors
Read your Amazon Ads campaigns, results, rules and activity, every marketplace and ad type.
Manage Apple Ads campaigns and reporting in chat.
Read-only Google Ads, Meta Ads and TikTok Ads performance, campaigns and creatives via OAuth.
Google Ads analysis and operations — read performance, manage keywords, bids, and campaigns.
Related MCP Servers
- AlicenseBqualityCmaintenanceProvides read-only access to TikTok advertising data, including campaigns, ad groups, ads, and performance reports through the TikTok Business API.699 PyPI46MIT
- FlicenseNot gradedqualityDmaintenanceRead-only access to Reddit Ads API v3 for listing ad accounts, campaigns, ad groups, ads, and generating performance reports with OAuth2 authentication.-
- AlicenseNot gradedqualityBmaintenanceEnables read-only analysis of Apple Ads Platform data, allowing AI assistants to query campaign structure, keywords, search terms, and performance reports without modifying anything.MIT
- AlicenseNot gradedqualityDmaintenanceProvides read-only tools for Reddit Ads, listing accounts, campaigns, ad groups, ads, and generating performance reports.1MIT