@channel47/meta-ads-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 channel47
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# @channel47/meta-ads-mcp
+
+MCP server for Meta Ads (Facebook + Instagram) using the Graph API (`v25.0`).
+
+This server exposes three tools expected by channel47 Meta workflows:
+
+- `list_accounts`
+- `query`
+- `mutate`
+
+## Installation
+
+### Standalone
+
+```bash
+npx @channel47/meta-ads-mcp@latest
+```
+
+### Monorepo Development
+
+```bash
+cd mcps
+npm install
+npm run test
+```
+
+## Configuration
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `META_ADS_ACCESS_TOKEN` | Meta Graph API access token (long-lived user token or system user token) |
+
+### Optional
+
+| Variable | Description |
+|----------|-------------|
+| `META_ADS_ACCOUNT_ID` | Default ad account ID used when `account_id` is omitted |
+| `META_ADS_READ_ONLY` | Set to `true` to disable live mutations |
+| `META_ADS_REQUEST_TIMEOUT_MS` | HTTP request timeout in milliseconds (default `30000`) |
+
+## Tool Reference
+
+### `list_accounts`
+
+List accessible ad accounts from `GET /me/adaccounts`.
+
+**Params:**
+- `status` (optional): status filter (`ACTIVE`, `DISABLED`, etc.)
+
+**Notes:**
+- Account IDs are normalized without `act_` prefix
+- Includes raw `account_status` and mapped status text
+- Follows Graph API cursor pagination to return all accessible accounts
+
+### `query`
+
+Structured query wrapper for Meta Graph API entities:
+
+- `campaigns`
+- `adsets`
+- `ads`
+- `insights`
+- `audiences`
+- `creatives`
+
+**Core params:**
+- `entity` (required)
+- `account_id` (optional if `META_ADS_ACCOUNT_ID` exists)
+- `fields`, `filters`, `sort`, `limit`
+- `inline_insights_fields` (optional on non-`insights` entities): appends nested inline projection like `insights{spend,ctr,frequency}`
+
+**Insights params:**
+- `date_range`: preset (`today`, `yesterday`, `last_7d`, `last_14d`, `last_30d`, `this_month`, `this_week_mon_today`, `last_quarter`) or `{ since, until }`
+- `level`: `campaign`, `adset`, or `ad`
+- `time_increment`: `1`, `7`, `monthly`, etc.
+- `breakdowns`: array of dimensions (`age`, `gender`, `publisher_platform`, etc.)
+
+### `mutate`
+
+Mutation tool with dry-run safety by default.
+
+**Operation format:**
+
+```json
+{
+  "entity": "campaign",
+  "action": "update",
+  "id": "123456789",
+  "params": {
+    "daily_budget": "5000"
+  }
+}
+```
+
+**Supported entities:**
+- `campaign`
+- `adset`
+- `ad`
+- `audience`
+- `creative`
+
+**Supported actions:**
+- `create`
+- `update`
+- `pause`
+- `enable`
+- `archive`
+- `delete`
+
+**Top-level params:**
+- `operations` (required)
+- `dry_run` (default `true`)
+- `partial_failure` (default `true`)
+
+## Behavior Notes
+
+- Auth is sent via `Authorization: Bearer <token>` request header
+- API retries once on:
+  - HTTP `429`
+  - Graph error codes `17` and `32`
+- For throttled retries, `Retry-After` header is used when available; otherwise fallback is `60s`
+- Requests are aborted on timeout (default `30000ms`, configurable via `META_ADS_REQUEST_TIMEOUT_MS`)
+- Budgets are returned in minor currency units (example: `5000` means `$50.00` USD)
+
+## Development Commands
+
+```bash
+cd meta-ads
+npm test
+node server/index.js
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@channel47/meta-ads-mcp",
+  "version": "1.0.0",
+  "description": "Meta Ads MCP Server - Query and mutate Meta/Facebook/Instagram ads data via Graph API",
+  "main": "server/index.js",
+  "bin": {
+    "meta-ads-mcp": "server/index.js"
+  },
+  "type": "module",
+  "files": [
+    "server/**/*.js",
+    "server/**/*.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "start": "node server/index.js",
+    "test": "node --test *.test.js test/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "meta-ads",
+    "facebook-ads",
+    "instagram-ads",
+    "analytics",
+    "advertising",
+    "claude"
+  ],
+  "author": "channel47",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/channel47/mcps.git",
+    "directory": "meta-ads"
+  },
+  "bugs": {
+    "url": "https://github.com/channel47/mcps/issues"
+  },
+  "homepage": "https://github.com/channel47/mcps/tree/main/meta-ads#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/server/auth.js

@@ -0,0 +1,40 @@
+const REQUIRED_ENV_VARS = ['META_ADS_ACCESS_TOKEN'];
+
+let cachedAccessToken = null;
+
+/**
+ * Validate required environment variables for Meta Ads auth.
+ * @returns {{ valid: boolean, missing: string[] }}
+ */
+export function validateEnvironment() {
+  const missing = REQUIRED_ENV_VARS.filter((name) => !process.env[name]);
+  return {
+    valid: missing.length === 0,
+    missing
+  };
+}
+
+/**
+ * Return the configured Meta Ads access token with process-level caching.
+ * @returns {Promise<string>}
+ */
+export async function getAccessToken() {
+  if (cachedAccessToken) {
+    return cachedAccessToken;
+  }
+
+  const { valid, missing } = validateEnvironment();
+  if (!valid) {
+    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+  }
+
+  cachedAccessToken = String(process.env.META_ADS_ACCESS_TOKEN);
+  return cachedAccessToken;
+}
+
+/**
+ * Clear the in-memory token cache (used by tests and local dev flows).
+ */
+export function clearAuthCache() {
+  cachedAccessToken = null;
+}

package/server/http.js

@@ -0,0 +1,186 @@
+import { getAccessToken } from './auth.js';
+import { invalidParamsError } from './utils/errors.js';
+
+const META_BASE_URL = 'https://graph.facebook.com/v25.0';
+const RATE_LIMIT_ERROR_CODES = new Set([17, 32]);
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RATE_LIMIT_SLEEP_MS = 60_000;
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+function normalizePath(path) {
+  if (!path) {
+    throw new Error('API path is required');
+  }
+
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+function buildUrl(path, params = {}) {
+  const url = new URL(`${META_BASE_URL}${normalizePath(path)}`);
+
+  for (const [key, value] of Object.entries(params)) {
+    if (value === undefined || value === null || value === '') {
+      continue;
+    }
+    url.searchParams.set(key, String(value));
+  }
+
+  return url;
+}
+
+async function parseResponse(response) {
+  const contentType = response.headers.get('content-type') || '';
+
+  if (contentType.includes('application/json')) {
+    return response.json();
+  }
+
+  const text = await response.text();
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function extractErrorCode(payload) {
+  return Number(payload?.error?.code || 0);
+}
+
+function extractErrorMessage(payload) {
+  if (payload?.error?.message) {
+    return payload.error.message;
+  }
+
+  if (payload?.message) {
+    return payload.message;
+  }
+
+  if (typeof payload === 'string' && payload) {
+    return payload;
+  }
+
+  return 'Unknown Meta Ads API error';
+}
+
+function resolveTimeoutMs(timeoutMs) {
+  const candidate = timeoutMs ?? process.env.META_ADS_REQUEST_TIMEOUT_MS ?? DEFAULT_TIMEOUT_MS;
+  const parsed = Number(candidate);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    return DEFAULT_TIMEOUT_MS;
+  }
+  return Math.floor(parsed);
+}
+
+function getRateLimitSleepMs(response) {
+  const retryAfter = response?.headers?.get('retry-after');
+  if (!retryAfter) {
+    return DEFAULT_RATE_LIMIT_SLEEP_MS;
+  }
+
+  const seconds = Number(retryAfter);
+  if (Number.isFinite(seconds) && seconds > 0) {
+    return Math.floor(seconds * 1000);
+  }
+
+  const retryAtMs = Date.parse(retryAfter);
+  if (Number.isFinite(retryAtMs)) {
+    const delta = retryAtMs - Date.now();
+    if (delta > 0) {
+      return Math.floor(delta);
+    }
+  }
+
+  return DEFAULT_RATE_LIMIT_SLEEP_MS;
+}
+
+/**
+ * Execute an authenticated Meta Graph API request with timeout and retry handling.
+ * @param {string} path
+ * @param {Record<string, unknown>} [params]
+ * @param {{
+ *   method?: string,
+ *   body?: unknown,
+ *   timeoutMs?: number,
+ *   retryThrottled?: boolean,
+ *   sleep?: (ms: number) => Promise<void>
+ * }} [options]
+ * @returns {Promise<unknown>}
+ */
+export async function metaRequest(
+  path,
+  params = {},
+  {
+    method = 'GET',
+    body,
+    timeoutMs,
+    retryThrottled = true,
+    sleep: sleepFn = sleep
+  } = {}
+) {
+  const token = await getAccessToken();
+  const url = buildUrl(path, params);
+  const resolvedTimeoutMs = resolveTimeoutMs(timeoutMs);
+  const controller = new AbortController();
+  const timeoutId = setTimeout(() => {
+    controller.abort();
+  }, resolvedTimeoutMs);
+
+  const requestOptions = {
+    method,
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${token}`
+    },
+    signal: controller.signal
+  };
+
+  if (body !== undefined && body !== null) {
+    requestOptions.body = typeof body === 'string' ? body : JSON.stringify(body);
+  }
+
+  let response;
+  try {
+    response = await fetch(url, requestOptions);
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw new Error(`Meta Ads API request timed out after ${resolvedTimeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  const payload = await parseResponse(response);
+
+  if (response.ok) {
+    return payload;
+  }
+
+  if (response.status === 401) {
+    const message = extractErrorMessage(payload);
+    throw invalidParamsError(`Meta Ads API request failed (${response.status}): ${message}`);
+  }
+
+  const errorCode = extractErrorCode(payload);
+  const isRateLimited = response.status === 429 || RATE_LIMIT_ERROR_CODES.has(errorCode);
+  if (isRateLimited && retryThrottled) {
+    await sleepFn(getRateLimitSleepMs(response));
+
+    return metaRequest(path, params, {
+      method,
+      body,
+      timeoutMs: resolvedTimeoutMs,
+      retryThrottled: false,
+      sleep: sleepFn
+    });
+  }
+
+  const message = extractErrorMessage(payload);
+  throw new Error(`Meta Ads API request failed (${response.status}): ${message}`);
+}

package/server/index.js

@@ -0,0 +1,208 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { validateEnvironment } from './auth.js';
+import { listAccounts } from './tools/list-accounts.js';
+import { query } from './tools/query.js';
+import { mutate } from './tools/mutate.js';
+import { getPromptsList, renderPrompt } from './prompts/templates.js';
+import { getResourcesList, readResource } from './resources/index.js';
+
+const SERVER_NAME = 'meta-ads-mcp';
+const SERVER_VERSION = '1.0.0';
+const READ_ONLY = process.env.META_ADS_READ_ONLY === 'true';
+
+const ALL_TOOLS = [
+  {
+    name: 'list_accounts',
+    description: 'List all accessible Meta ad accounts for the authenticated token.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        status: {
+          type: 'string',
+          description: 'Optional account status filter (e.g. ACTIVE, DISABLED)'
+        }
+      }
+    }
+  },
+  {
+    name: 'query',
+    description: 'Query campaigns, adsets, ads, insights, audiences, or creatives from Meta Graph API, including optional inline nested insights on non-insights entities.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        account_id: {
+          type: 'string',
+          description: 'Meta account ID. Supports either 123... or act_123...'
+        },
+        entity: {
+          type: 'string',
+          enum: ['campaigns', 'adsets', 'ads', 'insights', 'audiences', 'creatives'],
+          description: 'Entity type to query'
+        },
+        fields: {
+          anyOf: [
+            { type: 'string' },
+            {
+              type: 'array',
+              items: { type: 'string' }
+            }
+          ],
+          description: 'Optional fields selection. Defaults to entity-specific presets.'
+        },
+        inline_insights_fields: {
+          anyOf: [
+            { type: 'string' },
+            {
+              type: 'array',
+              items: { type: 'string' }
+            }
+          ],
+          description: 'For non-insights entities, append nested insights projection fields (e.g. spend,ctr,frequency)'
+        },
+        filters: {
+          type: 'array',
+          items: { type: 'object' },
+          description: 'Optional structured Graph filtering clauses'
+        },
+        date_range: {
+          anyOf: [{ type: 'string' }, { type: 'object' }],
+          description: 'Insights-only date range preset or { since, until } object'
+        },
+        level: {
+          type: 'string',
+          description: 'Insights-only breakdown level (campaign, adset, ad)'
+        },
+        time_increment: {
+          anyOf: [{ type: 'string' }, { type: 'integer' }],
+          description: 'Insights-only increment (1, 7, monthly, etc.)'
+        },
+        breakdowns: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Insights-only dimension breakdowns (e.g. age, gender, publisher_platform)'
+        },
+        limit: {
+          type: 'integer',
+          minimum: 1,
+          maximum: 1000,
+          description: 'Maximum rows to return (default: 100, max: 1000)'
+        },
+        sort: {
+          type: 'string',
+          description: 'Optional sort expression'
+        }
+      },
+      required: ['entity']
+    }
+  },
+  {
+    name: 'mutate',
+    description: 'Execute create/update/pause/enable/archive/delete operations for campaign, adset, ad, audience, and creative entities. dry_run defaults to true and performs server-side validation via Meta validate_only API. Creates default to PAUSED status for safety (pass explicit status to override). DELETE is permanent and unrecoverable — prefer pause or archive. Campaign creates require special_ad_categories (use [] if none apply).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        account_id: {
+          type: 'string',
+          description: 'Meta account ID. Supports either 123... or act_123...'
+        },
+        operations: {
+          type: 'array',
+          description: 'Array of operation objects: { entity, action, id?, params? }',
+          items: {
+            type: 'object'
+          }
+        },
+        dry_run: {
+          type: 'boolean',
+          description: 'Validate and preview only (default: true)',
+          default: true
+        },
+        partial_failure: {
+          type: 'boolean',
+          description: 'Continue executing later operations when one fails (default: true)',
+          default: true
+        }
+      },
+      required: ['operations']
+    }
+  }
+];
+
+const TOOLS = READ_ONLY ? ALL_TOOLS.filter((tool) => tool.name !== 'mutate') : ALL_TOOLS;
+
+const envStatus = validateEnvironment();
+if (!envStatus.valid) {
+  console.error(`Missing required environment variables: ${envStatus.missing.join(', ')}`);
+  process.exit(1);
+}
+
+if (READ_ONLY) {
+  console.error('Read-only mode enabled — mutate tool disabled');
+}
+
+const server = new Server(
+  {
+    name: SERVER_NAME,
+    version: SERVER_VERSION
+  },
+  {
+    capabilities: {
+      tools: {},
+      prompts: {},
+      resources: {}
+    }
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: params } = request.params;
+
+  if (name === 'list_accounts') {
+    return listAccounts(params);
+  }
+
+  if (name === 'query') {
+    return query(params);
+  }
+
+  if (name === 'mutate') {
+    if (READ_ONLY) {
+      throw new Error('mutate is disabled in read-only mode (META_ADS_READ_ONLY=true)');
+    }
+    return mutate(params);
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+});
+
+server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: getPromptsList() }));
+server.setRequestHandler(GetPromptRequestSchema, async (request) => (
+  renderPrompt(request.params.name, request.params.arguments || {})
+));
+
+server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: getResourcesList() }));
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => readResource(request.params.uri));
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`${SERVER_NAME} v${SERVER_VERSION} started`);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});