admob-mcp-server 0.1.0

package/dist/toolsets/mediation.js

@@ -0,0 +1,259 @@
+import { z } from 'zod';
+import { AD_FORMATS, PLATFORMS } from '../admob/constants.js';
+import { paginationShape, runTool } from './common.js';
+const mediationGroupLineSchema = z.object({
+    id: z
+        .string()
+        .optional()
+        .describe('Line ID. For new lines use distinct negative placeholders ("-1", "-2", ...)'),
+    displayName: z.string().describe('Display name of the line'),
+    adSourceId: z.string().describe('Ad source this line serves — get IDs from list_ad_sources'),
+    cpmMode: z
+        .enum(['LIVE', 'MANUAL', 'ANO'])
+        .optional()
+        .describe('CPM mode: LIVE (real-time from the network), MANUAL (fixed CPM), ANO (network-optimized)'),
+    cpmMicros: z
+        .number()
+        .optional()
+        .describe('Fixed CPM in micros of the account currency (only with cpmMode MANUAL)'),
+    adUnitMappings: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('Map of AdMob ad unit ID to ad unit mapping resource name (from create_ad_unit_mapping)'),
+});
+function toApiLine(line) {
+    return {
+        id: line.id,
+        displayName: line.displayName,
+        adSourceId: line.adSourceId,
+        cpmMode: line.cpmMode,
+        cpmMicros: line.cpmMicros != null ? String(line.cpmMicros) : undefined,
+        adUnitMappings: line.adUnitMappings,
+    };
+}
+export function registerMediationToolset(ctx) {
+    ctx.server.registerTool('list_ad_sources', {
+        title: 'List ad sources',
+        description: 'Lists the mediation ad sources (ad networks) available to the AdMob account, with their ad source IDs.',
+        inputSchema: { ...paginationShape },
+        annotations: { readOnlyHint: true },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.adSources.list({
+            parent: await ctx.accountName(),
+            pageSize: args.pageSize,
+            pageToken: args.pageToken,
+        });
+        return res.data;
+    }));
+    ctx.server.registerTool('list_adapters', {
+        title: 'List ad source adapters',
+        description: 'Lists the adapters of a mediation ad source, including the adapter ID and required ad unit configuration keys (needed for create_ad_unit_mapping).',
+        inputSchema: {
+            adSourceId: z.string().describe('Ad source ID from list_ad_sources'),
+            ...paginationShape,
+        },
+        annotations: { readOnlyHint: true },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.adSources.adapters.list({
+            parent: `${await ctx.accountName()}/adSources/${args.adSourceId}`,
+            pageSize: args.pageSize,
+            pageToken: args.pageToken,
+        });
+        return res.data;
+    }));
+    ctx.server.registerTool('list_mediation_groups', {
+        title: 'List mediation groups',
+        description: 'Lists the mediation groups in the AdMob account, including targeting (format, platform, ad units) and mediation lines.',
+        inputSchema: {
+            ...paginationShape,
+            filter: z
+                .string()
+                .optional()
+                .describe('Optional filter, e.g. \'AD_SOURCE_IDS IN ("5450213213286189855")\' or \'DISPLAY_NAME CONTAINS "waterfall"\''),
+        },
+        annotations: { readOnlyHint: true },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.mediationGroups.list({
+            parent: await ctx.accountName(),
+            pageSize: args.pageSize,
+            pageToken: args.pageToken,
+            filter: args.filter,
+        });
+        return res.data;
+    }));
+    ctx.server.registerTool('list_ad_unit_mappings', {
+        title: 'List ad unit mappings',
+        description: 'Lists the ad unit mappings (third-party network placements) attached to an AdMob ad unit.',
+        inputSchema: {
+            adUnitId: z
+                .string()
+                .describe('Ad unit ID, e.g. the numeric part after "/" in ca-app-pub-XXX/YYYYYYYYYY'),
+            ...paginationShape,
+        },
+        annotations: { readOnlyHint: true },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.adUnits.adUnitMappings.list({
+            parent: `${await ctx.accountName()}/adUnits/${args.adUnitId}`,
+            pageSize: args.pageSize,
+            pageToken: args.pageToken,
+        });
+        return res.data;
+    }));
+    if (ctx.readOnly)
+        return;
+    ctx.server.registerTool('create_ad_unit_mapping', {
+        title: 'Create ad unit mapping',
+        description: 'Creates an ad unit mapping that links an AdMob ad unit to a third-party network placement via an adapter. Get the adapter ID and required configuration keys from list_adapters. Requires the admob.monetization scope.',
+        inputSchema: {
+            adUnitId: z.string().describe('AdMob ad unit ID to attach the mapping to'),
+            adapterId: z.string().describe('Adapter ID from list_adapters'),
+            adUnitConfigurations: z
+                .record(z.string(), z.string())
+                .describe("Adapter configuration key/value pairs, keys from the adapter's adUnitConfigurations"),
+            displayName: z.string().optional().describe('Display name of the mapping'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.adUnits.adUnitMappings.create({
+            parent: `${await ctx.accountName()}/adUnits/${args.adUnitId}`,
+            requestBody: {
+                adapterId: args.adapterId,
+                adUnitConfigurations: args.adUnitConfigurations,
+                displayName: args.displayName,
+            },
+        });
+        return res.data;
+    }));
+    ctx.server.registerTool('create_mediation_group', {
+        title: 'Create mediation group',
+        description: 'Creates a mediation group targeting a format/platform and a set of ad units, with optional mediation lines for third-party ad sources. Requires the admob.monetization scope.',
+        inputSchema: {
+            displayName: z.string().describe('Display name of the mediation group'),
+            platform: z.enum(PLATFORMS).describe('Targeted platform'),
+            format: z.enum(AD_FORMATS).describe('Targeted ad format'),
+            adUnitIds: z
+                .array(z.string())
+                .min(1)
+                .describe('AdMob ad unit IDs this mediation group serves'),
+            targetedRegionCodes: z
+                .array(z.string())
+                .optional()
+                .describe('CLDR region codes to target (omit for all regions)'),
+            excludedRegionCodes: z
+                .array(z.string())
+                .optional()
+                .describe('CLDR region codes to exclude'),
+            idfaTargeting: z
+                .enum(['ALL', 'AVAILABLE', 'UNAVAILABLE'])
+                .optional()
+                .describe('iOS IDFA targeting'),
+            mediationGroupLines: z
+                .array(mediationGroupLineSchema)
+                .optional()
+                .describe('Mediation lines (ad sources) in the group'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const lines = args.mediationGroupLines?.map((line, i) => toApiLine({ ...line, id: line.id ?? String(-(i + 1)) }));
+        const res = await client.accounts.mediationGroups.create({
+            parent: await ctx.accountName(),
+            requestBody: {
+                displayName: args.displayName,
+                targeting: {
+                    platform: args.platform,
+                    format: args.format,
+                    adUnitIds: args.adUnitIds,
+                    targetedRegionCodes: args.targetedRegionCodes,
+                    excludedRegionCodes: args.excludedRegionCodes,
+                    idfaTargeting: args.idfaTargeting,
+                },
+                mediationGroupLines: lines
+                    ? Object.fromEntries(lines.map((line) => [line.id ?? '', line]))
+                    : undefined,
+            },
+        });
+        return res.data;
+    }));
+    ctx.server.registerTool('update_mediation_group', {
+        title: 'Update mediation group',
+        description: 'Patches a mediation group. Pass the fields to change in mediationGroup and list their paths in updateMask (e.g. "display_name,targeting.ad_unit_ids"). Requires the admob.monetization scope.',
+        inputSchema: {
+            mediationGroupId: z.string().describe('Mediation group ID from list_mediation_groups'),
+            updateMask: z
+                .string()
+                .describe('Comma-separated field mask, e.g. "display_name,mediation_group_lines"'),
+            mediationGroup: z
+                .record(z.string(), z.unknown())
+                .describe('MediationGroup fields to update, following the AdMob API v1beta MediationGroup schema'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.mediationGroups.patch({
+            name: `${await ctx.accountName()}/mediationGroups/${args.mediationGroupId}`,
+            updateMask: args.updateMask,
+            // Passthrough by design: the field mask decides the shape; Google validates it.
+            requestBody: args.mediationGroup,
+        });
+        return res.data;
+    }));
+    ctx.server.registerTool('create_mediation_ab_experiment', {
+        title: 'Create mediation A/B experiment',
+        description: 'Creates an A/B experiment on a mediation group: the treatment variant serves the given mediation lines against the existing setup. Requires the admob.monetization scope.',
+        inputSchema: {
+            mediationGroupId: z.string().describe('Mediation group ID to experiment on'),
+            displayName: z.string().describe('Display name of the experiment'),
+            treatmentTrafficPercentage: z
+                .number()
+                .int()
+                .min(1)
+                .max(99)
+                .optional()
+                .describe('Percentage of traffic sent to the treatment variant (1-99)'),
+            treatmentMediationLines: z
+                .array(mediationGroupLineSchema)
+                .min(1)
+                .describe('Mediation lines served by the treatment variant'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.mediationGroups.mediationAbExperiments.create({
+            parent: `${await ctx.accountName()}/mediationGroups/${args.mediationGroupId}`,
+            requestBody: {
+                displayName: args.displayName,
+                treatmentTrafficPercentage: args.treatmentTrafficPercentage != null
+                    ? String(args.treatmentTrafficPercentage)
+                    : undefined,
+                treatmentMediationLines: args.treatmentMediationLines.map((line) => ({
+                    mediationGroupLine: toApiLine(line),
+                })),
+            },
+        });
+        return res.data;
+    }));
+    ctx.server.registerTool('stop_mediation_ab_experiment', {
+        title: 'Stop mediation A/B experiment',
+        description: 'Stops the running A/B experiment on a mediation group by choosing the winning variant. Requires the admob.monetization scope.',
+        inputSchema: {
+            mediationGroupId: z.string().describe('Mediation group ID whose experiment to stop'),
+            variantChoice: z
+                .enum(['VARIANT_CHOICE_A', 'VARIANT_CHOICE_B'])
+                .describe('Winning variant to keep serving (A = control, B = treatment)'),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.mediationGroups.mediationAbExperiments.stop({
+            name: `${await ctx.accountName()}/mediationGroups/${args.mediationGroupId}/mediationAbExperiments`,
+            requestBody: { variantChoice: args.variantChoice },
+        });
+        return res.data;
+    }));
+}

package/dist/toolsets/reports.js

@@ -0,0 +1,108 @@
+import { z } from 'zod';
+import { CAMPAIGN_REPORT_DIMENSIONS, CAMPAIGN_REPORT_METRICS, DEFAULT_MAX_REPORT_ROWS, MAX_REPORT_ROWS_LIMIT, MEDIATION_REPORT_DIMENSIONS, MEDIATION_REPORT_METRICS, NETWORK_REPORT_DIMENSIONS, NETWORK_REPORT_METRICS, SORT_ORDERS, } from '../admob/constants.js';
+import { buildReportSpec, flattenReport, flattenRow, parseDate } from '../admob/reports.js';
+import { runTool } from './common.js';
+const dateSchema = z
+    .string()
+    .regex(/^\d{4}-\d{2}-\d{2}$/, 'Use YYYY-MM-DD')
+    .describe('Date in YYYY-MM-DD format');
+function reportInputShape(dimensions, metrics) {
+    return {
+        startDate: dateSchema.describe('Start date (YYYY-MM-DD), inclusive'),
+        endDate: dateSchema.describe('End date (YYYY-MM-DD), inclusive'),
+        metrics: z.array(z.enum(metrics)).min(1).describe('Metrics to report'),
+        dimensions: z.array(z.enum(dimensions)).optional().describe('Dimensions to group rows by'),
+        dimensionFilters: z
+            .array(z.object({
+            dimension: z.enum(dimensions),
+            values: z.array(z.string()).min(1).describe('Dimension values to match'),
+        }))
+            .optional()
+            .describe('Only include rows whose dimension matches one of the given values'),
+        sortConditions: z
+            .array(z.object({
+            dimension: z.enum(dimensions).optional(),
+            metric: z.enum(metrics).optional(),
+            order: z.enum(SORT_ORDERS),
+        }))
+            .optional()
+            .describe('Sort order — set either dimension or metric per condition'),
+        maxReportRows: z
+            .number()
+            .int()
+            .min(1)
+            .max(MAX_REPORT_ROWS_LIMIT)
+            .optional()
+            .describe(`Maximum rows to return (default ${DEFAULT_MAX_REPORT_ROWS})`),
+        currencyCode: z
+            .string()
+            .length(3)
+            .optional()
+            .describe('ISO 4217 currency for monetary metrics (default: account currency)'),
+    };
+}
+const MONETARY_NOTE = 'Monetary metrics are converted from micros to whole currency units (see currencyCode).';
+export function registerReportsToolset(ctx) {
+    ctx.server.registerTool('generate_network_report', {
+        title: 'Generate AdMob network report',
+        description: `Generates an AdMob Network earnings/performance report (requests, impressions, clicks, estimated earnings, match rate, RPM...). ${MONETARY_NOTE}`,
+        inputSchema: reportInputShape(NETWORK_REPORT_DIMENSIONS, NETWORK_REPORT_METRICS),
+        annotations: { readOnlyHint: true },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.networkReport.generate({
+            parent: await ctx.accountName(),
+            requestBody: { reportSpec: buildReportSpec(args) },
+        });
+        return flattenReport(res.data);
+    }));
+    ctx.server.registerTool('generate_mediation_report', {
+        title: 'Generate AdMob mediation report',
+        description: `Generates an AdMob Mediation report across ad sources (waterfall/bidding): impressions, estimated earnings, observed eCPM per AD_SOURCE, MEDIATION_GROUP, and more. ${MONETARY_NOTE}`,
+        inputSchema: reportInputShape(MEDIATION_REPORT_DIMENSIONS, MEDIATION_REPORT_METRICS),
+        annotations: { readOnlyHint: true },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.mediationReport.generate({
+            parent: await ctx.accountName(),
+            requestBody: { reportSpec: buildReportSpec(args) },
+        });
+        return flattenReport(res.data);
+    }));
+    ctx.server.registerTool('generate_campaign_report', {
+        title: 'Generate AdMob campaign report',
+        description: `Generates a report for AdMob cross-promotion campaigns: impressions, clicks, installs, estimated cost. Date range must be within the last 30 days. ${MONETARY_NOTE}`,
+        inputSchema: {
+            startDate: dateSchema.describe('Start date (YYYY-MM-DD), inclusive, within the last 30 days'),
+            endDate: dateSchema.describe('End date (YYYY-MM-DD), inclusive'),
+            metrics: z.array(z.enum(CAMPAIGN_REPORT_METRICS)).min(1).describe('Metrics to report'),
+            dimensions: z
+                .array(z.enum(CAMPAIGN_REPORT_DIMENSIONS))
+                .optional()
+                .describe('Dimensions to group rows by'),
+            languageCode: z
+                .string()
+                .optional()
+                .describe('IETF language tag for localized text, e.g. "en-US"'),
+        },
+        annotations: { readOnlyHint: true },
+    }, async (args) => runTool(async () => {
+        const client = await ctx.client();
+        const res = await client.accounts.campaignReport.generate({
+            parent: await ctx.accountName(),
+            requestBody: {
+                reportSpec: {
+                    dateRange: {
+                        startDate: parseDate(args.startDate),
+                        endDate: parseDate(args.endDate),
+                    },
+                    metrics: args.metrics,
+                    dimensions: args.dimensions,
+                    languageCode: args.languageCode,
+                },
+            },
+        });
+        const rows = (res.data.rows ?? []).map(flattenRow);
+        return { rowCount: rows.length, rows };
+    }));
+}

package/dist/version.js

@@ -0,0 +1,4 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const VERSION = pkg.version;

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "admob-mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for the Google AdMob API — apps, ad units, mediation, and revenue reports",
+  "type": "module",
+  "license": "MIT",
+  "author": "Ted Park <gun0912@naver.com> (https://github.com/ParkSangGwon)",
+  "mcpName": "io.github.parksanggwon/admob-mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ParkSangGwon/admob-mcp-server.git"
+  },
+  "homepage": "https://github.com/ParkSangGwon/admob-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/ParkSangGwon/admob-mcp-server/issues"
+  },
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "mcp-server",
+    "admob",
+    "google-admob",
+    "admob-api",
+    "monetization",
+    "ad-revenue",
+    "claude",
+    "llm"
+  ],
+  "bin": {
+    "admob-mcp-server": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "watch": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "inspect": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@googleapis/admob": "^6.0.2",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "googleapis-common": "^8.0.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "eslint": "^9.0.0",
+    "prettier": "^3.9.5",
+    "shx": "^0.4.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.0.0",
+    "vitest": "^4.1.10"
+  }
+}