@channel47/linkedin-ads-mcp 0.1.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,177 @@
+# @channel47/linkedin-ads-mcp
+
+MCP server for LinkedIn Ads using the LinkedIn Marketing API (versioned REST, default `LinkedIn-Version: 202605`).
+
+This server exposes four tools expected by channel47 LinkedIn workflows:
+
+- `list_accounts`
+- `query`
+- `analytics`
+- `mutate`
+
+## Installation
+
+### Standalone
+
+```bash
+npx @channel47/linkedin-ads-mcp@latest
+```
+
+### Monorepo Development
+
+```bash
+cd mcps
+npm install
+npm run test
+```
+
+### Claude Code
+
+```bash
+claude mcp add linkedin-ads --env LINKEDIN_ADS_ACCESS_TOKEN=<token> -- npx @channel47/linkedin-ads-mcp@latest
+```
+
+Or as JSON config:
+
+```json
+{
+  "mcpServers": {
+    "linkedin-ads": {
+      "command": "npx",
+      "args": ["@channel47/linkedin-ads-mcp@latest"],
+      "env": {
+        "LINKEDIN_ADS_ACCESS_TOKEN": "<token>"
+      }
+    }
+  }
+}
+```
+
+## Getting Credentials
+
+1. Create an app at [developer.linkedin.com](https://developer.linkedin.com/) and associate it with a LinkedIn Company Page.
+2. Request access to the **Advertising API** product (approval required).
+3. Complete the 3-legged OAuth flow with the `r_ads` scope (read) plus `rw_ads` (mutations) and `r_ads_reporting` (analytics) to obtain a member access token (valid 60 days).
+4. Either paste that token into `LINKEDIN_ADS_ACCESS_TOKEN`, or — if your app is enabled for programmatic refresh — supply client ID/secret and the refresh token (valid 1 year) and let the server refresh automatically.
+
+## Configuration
+
+### Required (one of the two auth modes)
+
+| Variable | Description |
+|----------|-------------|
+| `LINKEDIN_ADS_ACCESS_TOKEN` | Static LinkedIn OAuth access token, used directly |
+| `LINKEDIN_ADS_CLIENT_ID` + `LINKEDIN_ADS_CLIENT_SECRET` + `LINKEDIN_ADS_REFRESH_TOKEN` | OAuth refresh flow. When all three are set the server exchanges the refresh token at `https://www.linkedin.com/oauth/v2/accessToken`, caches the access token in memory, and refreshes ~5 minutes before expiry. Takes precedence over the static token. |
+
+### Optional
+
+| Variable | Description |
+|----------|-------------|
+| `LINKEDIN_ADS_ACCOUNT_ID` | Default ad account ID used when `account_id` is omitted |
+| `LINKEDIN_ADS_API_VERSION` | `LinkedIn-Version` header override in `YYYYMM` format (default `202605`) |
+| `LINKEDIN_ADS_READ_ONLY` | Set to `true` to disable live mutations |
+| `LINKEDIN_ADS_REQUEST_TIMEOUT_MS` | HTTP request timeout in milliseconds (default `30000`) |
+
+## Tool Reference
+
+### `list_accounts`
+
+List accessible ad accounts from `GET /rest/adAccounts?q=search` with cursor (`pageSize`/`pageToken`) pagination.
+
+**Params:**
+- `status` (optional): `ACTIVE`, `CANCELED`, `DRAFT`, `PENDING_DELETION`, `REMOVED` — string or array, applied server-side via the search finder
+- `type` (optional): `BUSINESS`, `ENTERPRISE`
+- `limit` (optional, default 1000)
+
+Returns id, name, status, currency, type, test flag, organization reference, and serving statuses per account.
+
+### `query`
+
+Entity reads for one ad account:
+
+| `entity` | Endpoint | Finder |
+|----------|----------|--------|
+| `campaigns` | `/rest/adAccounts/{id}/adCampaigns` | `q=search` |
+| `campaign_groups` | `/rest/adAccounts/{id}/adCampaignGroups` | `q=search` |
+| `creatives` | `/rest/adAccounts/{id}/creatives` | `q=criteria` |
+
+**Params:**
+- `entity` (required)
+- `account_id` (optional if `LINKEDIN_ADS_ACCOUNT_ID` exists; accepts `123` or `urn:li:sponsoredAccount:123`)
+- `status` (optional): e.g. `ACTIVE`, `PAUSED`, `DRAFT`, `ARCHIVED` — for creatives this filters `intendedStatus`
+- `campaign_ids` (creatives only): restrict creatives to these campaigns
+- `limit` (default 100; creatives paginate at LinkedIn's max page size of 100, others at 1000)
+
+### `analytics`
+
+Metrics from `GET /rest/adAnalytics?q=analytics`.
+
+**Params:**
+- `pivot` (required): `ACCOUNT`, `CAMPAIGN_GROUP`, `CAMPAIGN`, `CREATIVE`
+- `start` (required) / `end` (optional): `YYYY-MM-DD`; encoded as the Rest.li `dateRange` expression
+- `time_granularity`: `ALL` (default), `DAILY`, `MONTHLY`
+- `entity_type` (default `account`) + `entity_ids`: plain IDs are converted to sponsored URNs and sent as the matching facet param (`accounts=List(...)`, `campaigns=List(...)`, ...). When omitted, the report is scoped to the account.
+- `fields`: defaults to `impressions, clicks, costInLocalCurrency, externalWebsiteConversions, dateRange, pivotValues`
+
+**Notes:**
+- LinkedIn allows at most **20 metric fields** per call; the server enforces this.
+- adAnalytics has **no pagination** — LinkedIn caps responses at 15,000 elements. Narrow the date range or entity list if you hit the cap.
+
+### `mutate`
+
+Mutation tool with dry-run safety by default.
+
+**Operation format:**
+
+```json
+{
+  "entity": "campaign",
+  "action": "update",
+  "id": "123456789",
+  "params": {
+    "dailyBudget": { "amount": "75", "currencyCode": "USD" }
+  }
+}
+```
+
+**Supported entities:** `campaign`, `campaign_group`, `creative`
+
+**Supported actions:**
+- `create` — POST to the entity collection under the account. New entities default to `DRAFT` status (`intendedStatus` for creatives), LinkedIn's safe non-serving state; pass an explicit status to override. The account URN is filled in automatically; creative creates require `params.campaign`.
+- `update` — Rest.li partial update: POST to the entity item with `X-RestLi-Method: PARTIAL_UPDATE` and body `{ "patch": { "$set": { ... } } }`
+- `pause` / `enable` / `archive` — status shortcuts via partial update (`PAUSED` / `ACTIVE` / `ARCHIVED`; creatives use `intendedStatus`)
+
+**Top-level params:**
+- `operations` (required)
+- `dry_run` (default `true`): LinkedIn has **no server-side validate-only mode**, so dry run performs local validation and returns a preview of the exact requests (method, path, headers, body) without calling the API
+- `partial_failure` (default `true`)
+
+**Safety notes:**
+- `archive` is hard to reverse — prefer `pause`.
+- Deletion (`PENDING_DELETION`) is deliberately not exposed.
+- Creative IDs are URNs (`urn:li:sponsoredCreative:123`); plain numeric IDs are accepted and converted.
+
+## Behavior Notes
+
+- Every request sends `Authorization: Bearer <token>`, `LinkedIn-Version` (default `202605`, override via `LINKEDIN_ADS_API_VERSION`), and `X-Restli-Protocol-Version: 2.0.0`.
+- Query strings use Rest.li 2.0 encoding: `List(...)` params keep literal parens/commas with percent-encoded items (`campaigns=List(urn%3Ali%3AsponsoredCampaign%3A123)`), and `dateRange=(start:(year:2026,month:6,day:1),end:(...))` keeps literal structure. `URLSearchParams` is never used for these.
+- API retries once on HTTP `429`, using the `Retry-After` header when available (fallback `60s`).
+- Requests are aborted on timeout (default `30000ms`, configurable via `LINKEDIN_ADS_REQUEST_TIMEOUT_MS`).
+- Created entity IDs are read from the `x-restli-id` response header.
+- LinkedIn API versions are supported for roughly one year; bump `LINKEDIN_ADS_API_VERSION` if requests start failing with version errors.
+
+## Read-Only Mode
+
+Set `LINKEDIN_ADS_READ_ONLY=true` to remove the `mutate` tool entirely. Dry runs are unaffected in normal mode; live execution is blocked even if a mutate call slips through.
+
+## Development Commands
+
+```bash
+cd linkedin-ads
+npm test
+node server/index.js
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@channel47/linkedin-ads-mcp",
+  "version": "0.1.0",
+  "description": "LinkedIn Ads MCP Server - Query and mutate LinkedIn Marketing API campaign data via versioned REST",
+  "main": "server/index.js",
+  "bin": {
+    "linkedin-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",
+    "linkedin-ads",
+    "linkedin-marketing-api",
+    "analytics",
+    "advertising",
+    "claude"
+  ],
+  "author": "channel47",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/channel47/mcps.git",
+    "directory": "linkedin-ads"
+  },
+  "bugs": {
+    "url": "https://github.com/channel47/mcps/issues"
+  },
+  "homepage": "https://github.com/channel47/mcps/tree/main/linkedin-ads#readme",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/server/auth.js

@@ -0,0 +1,146 @@
+const TOKEN_URL = 'https://www.linkedin.com/oauth/v2/accessToken';
+const REFRESH_BUFFER_MS = 5 * 60 * 1000;
+const DEFAULT_TOKEN_TTL_SECONDS = 3600;
+
+const REFRESH_FLOW_ENV_VARS = [
+  'LINKEDIN_ADS_CLIENT_ID',
+  'LINKEDIN_ADS_CLIENT_SECRET',
+  'LINKEDIN_ADS_REFRESH_TOKEN'
+];
+
+let cachedAccessToken = null;
+let accessTokenExpiresAt = 0;
+let refreshPromise = null;
+
+/**
+ * Check whether the full OAuth refresh-token credential set is configured.
+ * @returns {boolean}
+ */
+export function hasRefreshFlowCredentials() {
+  return REFRESH_FLOW_ENV_VARS.every((name) => Boolean(process.env[name]));
+}
+
+/**
+ * Validate environment variables for LinkedIn Ads auth. Auth is valid with
+ * either a static LINKEDIN_ADS_ACCESS_TOKEN or the complete refresh trio
+ * (LINKEDIN_ADS_CLIENT_ID + LINKEDIN_ADS_CLIENT_SECRET + LINKEDIN_ADS_REFRESH_TOKEN).
+ * @returns {{ valid: boolean, missing: string[] }}
+ */
+export function validateEnvironment() {
+  if (process.env.LINKEDIN_ADS_ACCESS_TOKEN || hasRefreshFlowCredentials()) {
+    return { valid: true, missing: [] };
+  }
+
+  const partialRefreshConfig = REFRESH_FLOW_ENV_VARS.some((name) => Boolean(process.env[name]));
+  const missing = partialRefreshConfig
+    ? REFRESH_FLOW_ENV_VARS.filter((name) => !process.env[name])
+    : ['LINKEDIN_ADS_ACCESS_TOKEN'];
+
+  return {
+    valid: false,
+    missing
+  };
+}
+
+function isCachedTokenValid() {
+  return Boolean(cachedAccessToken) && Date.now() < accessTokenExpiresAt - REFRESH_BUFFER_MS;
+}
+
+async function parseTokenResponse(response) {
+  let payload;
+  try {
+    payload = await response.json();
+  } catch (error) {
+    throw new Error(`Failed parsing LinkedIn OAuth token response: ${error.message}`);
+  }
+
+  if (!response.ok) {
+    const detail = payload?.error_description || payload?.error || 'unknown_error';
+    throw new Error(`LinkedIn OAuth token refresh failed (${response.status}): ${detail}`);
+  }
+
+  if (!payload?.access_token) {
+    throw new Error('LinkedIn OAuth token response missing access_token');
+  }
+
+  return payload;
+}
+
+async function performAccessTokenRefresh() {
+  const body = new URLSearchParams({
+    grant_type: 'refresh_token',
+    refresh_token: process.env.LINKEDIN_ADS_REFRESH_TOKEN,
+    client_id: process.env.LINKEDIN_ADS_CLIENT_ID,
+    client_secret: process.env.LINKEDIN_ADS_CLIENT_SECRET
+  });
+
+  const response = await fetch(TOKEN_URL, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/x-www-form-urlencoded'
+    },
+    body
+  });
+
+  const payload = await parseTokenResponse(response);
+  const expiresInMs = Number(payload.expires_in ?? DEFAULT_TOKEN_TTL_SECONDS) * 1000;
+
+  cachedAccessToken = payload.access_token;
+  accessTokenExpiresAt = Date.now() + expiresInMs;
+
+  return cachedAccessToken;
+}
+
+/**
+ * Force a token refresh via the LinkedIn OAuth refresh_token grant.
+ * Concurrent callers share a single in-flight refresh.
+ * @returns {Promise<string>}
+ */
+export async function refreshAccessToken() {
+  if (!refreshPromise) {
+    refreshPromise = performAccessTokenRefresh().finally(() => {
+      refreshPromise = null;
+    });
+  }
+
+  return refreshPromise;
+}
+
+/**
+ * Return a valid LinkedIn access token. Prefers the OAuth refresh flow when
+ * the full credential trio is configured (tokens are cached in memory and
+ * refreshed ~5 minutes before expiry); otherwise the static
+ * LINKEDIN_ADS_ACCESS_TOKEN is used directly.
+ * @returns {Promise<string>}
+ */
+export async function getAccessToken() {
+  if (hasRefreshFlowCredentials()) {
+    if (isCachedTokenValid()) {
+      return cachedAccessToken;
+    }
+
+    return refreshAccessToken();
+  }
+
+  if (cachedAccessToken) {
+    return cachedAccessToken;
+  }
+
+  const { valid, missing } = validateEnvironment();
+  if (!valid) {
+    throw new Error(`Missing required environment variables: ${missing.join(', ')}`);
+  }
+
+  cachedAccessToken = String(process.env.LINKEDIN_ADS_ACCESS_TOKEN);
+  accessTokenExpiresAt = Number.MAX_SAFE_INTEGER;
+  return cachedAccessToken;
+}
+
+/**
+ * Clear the in-memory token cache (used by tests and local dev flows).
+ */
+export function clearAuthCache() {
+  cachedAccessToken = null;
+  accessTokenExpiresAt = 0;
+  refreshPromise = null;
+}

package/server/http.js

@@ -0,0 +1,216 @@
+import { getAccessToken } from './auth.js';
+import { invalidParamsError } from './utils/errors.js';
+import { buildQueryString } from './utils/restli.js';
+
+/**
+ * Base URL for all LinkedIn Marketing API (versioned REST) requests.
+ */
+export const LINKEDIN_BASE_URL = 'https://api.linkedin.com/rest';
+/**
+ * Default LinkedIn-Version header (YYYYMM). Override with LINKEDIN_ADS_API_VERSION.
+ */
+export const DEFAULT_API_VERSION = '202605';
+/**
+ * Rest.li protocol version required on every request.
+ */
+export const RESTLI_PROTOCOL_VERSION = '2.0.0';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_RATE_LIMIT_SLEEP_MS = 60_000;
+
+function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+/**
+ * Resolve the LinkedIn-Version header value (YYYYMM). Invalid overrides fall
+ * back to the default version.
+ * @returns {string}
+ */
+export function getApiVersion() {
+  const configured = String(process.env.LINKEDIN_ADS_API_VERSION || '').trim();
+  return /^\d{6}$/.test(configured) ? configured : DEFAULT_API_VERSION;
+}
+
+function normalizePath(path) {
+  if (!path) {
+    throw new Error('API path is required');
+  }
+
+  return path.startsWith('/') ? path : `/${path}`;
+}
+
+function buildUrl(path, params = {}) {
+  const queryString = buildQueryString(params);
+  const base = `${LINKEDIN_BASE_URL}${normalizePath(path)}`;
+  return queryString ? `${base}?${queryString}` : base;
+}
+
+async function parseResponse(response) {
+  if (response.status === 204) {
+    return {};
+  }
+
+  const contentType = response.headers.get('content-type') || '';
+
+  if (contentType.includes('application/json')) {
+    return response.json();
+  }
+
+  const text = await response.text();
+  if (!text) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+
+function extractErrorMessage(payload) {
+  if (payload?.message) {
+    return payload.message;
+  }
+
+  if (payload?.error_description) {
+    return payload.error_description;
+  }
+
+  if (typeof payload === 'string' && payload) {
+    return payload;
+  }
+
+  return 'Unknown LinkedIn Ads API error';
+}
+
+function resolveTimeoutMs(timeoutMs) {
+  const candidate = timeoutMs ?? process.env.LINKEDIN_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 LinkedIn Marketing API request with Rest.li 2.0
+ * query encoding, versioned headers, timeout, and single-retry rate-limit
+ * handling. Created-entity IDs from the x-restli-id response header are
+ * surfaced on the returned payload as `restliId`.
+ * @param {string} path
+ * @param {Record<string, unknown>} [params]
+ * @param {{
+ *   method?: string,
+ *   body?: unknown,
+ *   headers?: Record<string, string>,
+ *   timeoutMs?: number,
+ *   retryThrottled?: boolean,
+ *   sleep?: (ms: number) => Promise<void>
+ * }} [options]
+ * @returns {Promise<unknown>}
+ */
+export async function linkedinRequest(
+  path,
+  params = {},
+  {
+    method = 'GET',
+    body,
+    headers = {},
+    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}`,
+      'LinkedIn-Version': getApiVersion(),
+      'X-Restli-Protocol-Version': RESTLI_PROTOCOL_VERSION,
+      ...headers
+    },
+    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(`LinkedIn Ads API request timed out after ${resolvedTimeoutMs}ms`);
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeoutId);
+  }
+
+  const payload = await parseResponse(response);
+
+  if (response.ok) {
+    const restliId = response.headers.get('x-restli-id') || response.headers.get('x-linkedin-id');
+    if (restliId && payload && typeof payload === 'object' && !Array.isArray(payload)) {
+      return { ...payload, restliId };
+    }
+    return payload;
+  }
+
+  if (response.status === 401) {
+    const message = extractErrorMessage(payload);
+    throw invalidParamsError(`LinkedIn Ads API request failed (${response.status}): ${message}`);
+  }
+
+  if (response.status === 429 && retryThrottled) {
+    await sleepFn(getRateLimitSleepMs(response));
+
+    return linkedinRequest(path, params, {
+      method,
+      body,
+      headers,
+      timeoutMs: resolvedTimeoutMs,
+      retryThrottled: false,
+      sleep: sleepFn
+    });
+  }
+
+  const message = extractErrorMessage(payload);
+  throw new Error(`LinkedIn Ads API request failed (${response.status}): ${message}`);
+}