Aapl Ads MCP

What andrealufino/aapl-ads-mcp MCP server does

The andrealufino/aapl-ads-mcp MCP server gives an MCP client read-only access to an Apple Search Ads account. It queries Apple Search Ads API v5 for campaign structures and advertising performance, allowing an assistant to answer questions about campaigns, ad groups, targeting keywords, search terms, spend, and installs.

The available operations include checking accessible organizations, listing campaigns with optional status filtering, retrieving ad groups for a campaign, and listing keywords with bid amounts and match types. Reporting operations provide campaign-, ad group-, and keyword-level metrics such as impressions, taps, installs, spend, CPI, and TTR. A search terms report shows the queries that caused ads to appear.

No create, update, pause, or other mutation operation is provided. The server is intended for inspection, reporting, and ad hoc analysis rather than campaign management.

How it works

The andrealufino/aapl-ads-mcp MCP server uses the MCP stdio transport. A local Node.js process is started by the MCP client, and the process makes authenticated requests to Apple Search Ads API v5. Claude Desktop is the documented client configuration example, but the README states that any MCP-compatible client can connect through the same transport.

Authentication uses an Apple Search Ads API user and an ES256 key pair. The client ID, team ID, key ID, organization ID, and private key are supplied through environment variables. The organization ID is fixed in configuration, so one running configuration targets a single organization rather than switching between multiple organizations.

Queries default to the most recent 30 days. Report calls can use hourly, daily, weekly, or monthly granularity. Aggregate install fields returned by Apple Search Ads do not require an SDK or app-side integration; separate attribution inside an app is outside this server's role.

Setup and configuration

To run the andrealufino/aapl-ads-mcp MCP server, use Node.js 20 or newer, clone the repository, install its dependencies, and build it with the included npm scripts. The resulting entry point is dist/index.js, which is launched with Node by the MCP client.

Before connecting, generate a P-256 ES256 private key in PKCS#8 format and derive its public key. Upload the public key when creating an API client in Apple Search Ads. The API user should have read-only access for the server's intended use. Apple Search Ads then provides the client, team, and key identifiers; the organization ID is found in account settings.

Configure these values in the MCP client's environment section:

• ASA_CLIENT_ID
• ASA_TEAM_ID
• ASA_KEY_ID
• ASA_ORG_ID
• ASA_PRIVATE_KEY_PATH, pointing to an absolute PEM path
• ASA_PRIVATE_KEY, containing the PEM directly when a mounted file is impractical

If both private-key variables are set, the inline ASA_PRIVATE_KEY value takes precedence. The path must be absolute because tilde expansion is not performed by Node.js. Keep the private key outside the repository when possible, and do not commit PEM or environment files.

Limitations and notes

The andrealufino/aapl-ads-mcp MCP server is read-only in the documented release. It cannot create campaigns, modify settings, change bids, pause ads, or perform other write actions. It also supports one configured organization at a time.

Access depends on Apple Search Ads Campaign Management API permissions and valid ES256 credentials. The server does not replace Apple's API access setup. Its reporting is based on data available from Apple Search Ads; app-side AdServices or AdAttributionKit integration is only relevant to separate in-app attribution requirements.

The repository is licensed under MIT. The access token is held in memory rather than written to disk, but the API credentials and private key still need to be protected and rotated if exposed.