# Cesteral MCP Servers Self-hostable MCP connectors for major advertising platforms. Use this repo when you want transparent platform integrations, local experimentation, and infrastructure you control. Use **Cesteral Intelligence** when your team needs approvals before spend commits, credential brokering, auditability, and cross-platform execution from one governed environment. [**Try Meta Ads MCP locally (~10 min)**](docs/guides/quickstart.md#path-a-meta-ads-recommended) | [**Compare OSS vs Cesteral Intelligence**](https://cesteral.com/compare?utm_source=github&utm_medium=readme&utm_campaign=hero) | [**Book a workflow demo**](mailto:sales@cesteral.com?subject=Workflow%20demo%20-%20Cesteral%20MCP%20Servers) [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE.md) [![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/) [![MCP](https://img.shields.io/badge/MCP-2025--11--25-green)](https://modelcontextprotocol.io/)

--- ## Two Ways to Use This This repo is an **open connector layer**, not the full product. - **Self-host a connector** for transparency and direct control of your credentials, infrastructure, and platform access. - **Use Cesteral Intelligence** when the workflow needs governed writes, team approvals, credential brokering, auditability, and cross-platform coordination — see [when you need it](#when-you-need-cesteral-intelligence) below. --- ## Flagship Connectors ###

Google Ads MCP Campaign writes, GAQL reporting, bid adjustments, previews, and validation via Google Ads REST API v25. [Package docs](packages/gads-mcp) | [Use with Cesteral Intelligence](https://cesteral.com/integrations/google-ads?utm_source=github&utm_medium=readme&utm_campaign=gads-mcp) ###

Meta Ads MCP Campaign writes, insights, targeting discovery, delivery estimates, previews, and bulk operations via Meta Marketing API v26.0. [Package docs](packages/meta-mcp) | [Use with Cesteral Intelligence](https://cesteral.com/integrations/meta-ads?utm_source=github&utm_medium=readme&utm_campaign=meta-mcp) ###

DV360 MCP Campaign writes, targeting, custom bidding, previews, uploads, and schema-driven validation via DV360 API v4. [Package docs](packages/dv360-mcp) | [Use with Cesteral Intelligence](https://cesteral.com/integrations/dv360?utm_source=github&utm_medium=readme&utm_campaign=dv360-mcp) --- ## When You Need Cesteral Intelligence The OSS connectors give you per-server tool execution + audit logs. Cesteral Intelligence layers governance and orchestration on top: - **Credential brokering** -- keep platform secrets out of local operator workflows - **Approval workflows** -- require human review before destructive or high-spend changes - **Aggregated audit** -- unified, cross-server activity feed with provenance, tied to operator identity - **Cross-platform orchestration** -- coordinate governed execution across multiple connectors - **Team operations** -- shared workflows, tenant isolation, and operator visibility [Compare OSS connectors vs Cesteral Intelligence](https://cesteral.com/compare?utm_source=github&utm_medium=readme&utm_campaign=why-managed) --- ## The Full Fleet | Server | Platform | Tools | Auth | | ----------------------------------------- | --------------------------------- | ----- | ------------------------------- | | [gads-mcp](packages/gads-mcp) | Google Ads REST API v25 | 18 | OAuth2 refresh token | | [meta-mcp](packages/meta-mcp) | Meta Marketing API v26.0 | 27 | Bearer token | | [dv360-mcp](packages/dv360-mcp) | DV360 API v4 | 26 | Google OAuth2 / service account | | [ttd-mcp](packages/ttd-mcp) | The Trade Desk REST + GraphQL API | 46 | User token (TTD-Auth header) | | [linkedin-mcp](packages/linkedin-mcp) | LinkedIn Marketing API (202608) | 23 | Bearer token | | [tiktok-mcp](packages/tiktok-mcp) | TikTok Marketing API v1.3 | 25 | Bearer token + advertiser ID | | [cm360-mcp](packages/cm360-mcp) | CM360 API v5 | 22 | Google OAuth2 | | [sa360-mcp](packages/sa360-mcp) | SA360 Reporting API v0 + DS v2 | 17 | OAuth2 refresh token | | [pinterest-mcp](packages/pinterest-mcp) | Pinterest Ads API v5 | 24 | Bearer token | | [snapchat-mcp](packages/snapchat-mcp) | Snapchat Ads API v1 | 25 | Bearer token | | [amazon-dsp-mcp](packages/amazon-dsp-mcp) | Amazon Ads Unified API (DSP) | 28 | Bearer token | | [msads-mcp](packages/msads-mcp) | Microsoft Advertising API v13 | 28 | Access token + developer token | | [dbm-mcp](packages/dbm-mcp) | Bid Manager API v2 | 6 | Google OAuth2 | Thirteen servers, 290+ tools. Tool counts are the live registered total per server, including the `*_search_tools` discovery tool where present. ### What Every Server Ships Every server speaks MCP protocol revisions `2025-03-26`, `2025-06-18` and `2025-11-25`, the ones `@modelcontextprotocol/sdk` 1.31.0 implements; the Streamable HTTP transport rejects any other `MCP-Protocol-Version`. The current revision, `2026-07-28`, is not supported yet ([#242](https://github.com/cesteral/mcp-open-advertising/issues/242)). That is not the whole spec. In the MCP conformance suite (`@modelcontextprotocol/conformance` 0.1.16) every server passes 18 of the 30 active server scenarios — initialize, ping, logging level and log notifications, tool list and call, elicitation (form, defaults and enums), resource list, read and templates, prompt list and get, concurrent SSE streams, DNS-rebinding protection — and [`conformance/expected-failures.yaml`](conformance/expected-failures.yaml) gives the reason for each of the other 12. Not implemented: completions, resource subscriptions, sampling, progress notifications, image / audio / embedded-resource content, and SSE stream resumption. Elicitation requests (including the destructive-action confirmations below) and log notifications are sent on the calling `tools/call` request's response stream, so a client does not need the optional GET stream to receive them. A server bound to a loopback address (the default outside `NODE_ENV=production`) accepts only loopback `Host` and `Origin` headers on `/mcp`; a server on any other address checks `Host` only when `MCP_ALLOWED_HOSTS` is set. Beyond raw tool calls, every server ships: - **MCP Prompts** — on-demand, multi-step workflow guidance (campaign launch, reporting, troubleshooting) so agents don't have to rediscover each platform's sequencing. Present on all 13 servers. - **MCP Resources** — structured, addressable context (schemas, field catalogs, examples, enums) fetched on demand instead of bloating every tool schema. Present on all 13 servers. DV360 uses these to keep its >1 MB discriminated unions off the wire (`entity-schema://`, `entity-fields://`, `entity-examples://`). - **Tool discovery** — a `_search_tools` tool that lets an agent search the server's own catalog by intent instead of paging the full list. On 10 of the 13 servers (all except the small `gads-mcp` and `sa360-mcp` / reporting-only `dbm-mcp`). - **Server discovery cards** — SEP-2127 metadata at `/.well-known/mcp/server-card.json` (name, version, transports, auth modes, capabilities) on every server, in every auth mode. - **OAuth resource discovery** — in `jwt` auth mode, the RFC 9728 endpoint at `/.well-known/oauth-protected-resource`. - **Report CSV spill** — large report bodies spill to GCS behind a signed URL so responses stay bounded. On the six reporting-heavy servers: `ttd-mcp`, `tiktok-mcp`, `snapchat-mcp`, `amazon-dsp-mcp`, `pinterest-mcp`, `msads-mcp`. | Server | Discovery | Prompts | Resources | CSV spill | | -------------- | :-------: | :-----: | :-------: | :-------: | | gads-mcp | | ✅ | ✅ | | | meta-mcp | ✅ | ✅ | ✅ | | | dv360-mcp | ✅ | ✅ | ✅ | | | ttd-mcp | ✅ | ✅ | ✅ | ✅ | | linkedin-mcp | ✅ | ✅ | ✅ | | | tiktok-mcp | ✅ | ✅ | ✅ | ✅ | | cm360-mcp | ✅ | ✅ | ✅ | | | sa360-mcp | | ✅ | ✅ | | | pinterest-mcp | ✅ | ✅ | ✅ | ✅ | | snapchat-mcp | ✅ | ✅ | ✅ | ✅ | | amazon-dsp-mcp | ✅ | ✅ | ✅ | ✅ | | msads-mcp | ✅ | ✅ | ✅ | ✅ | | dbm-mcp | | ✅ | ✅ | | --- ## Built for Production Self-hosting an AI agent that touches live ad spend is a trust problem first and a capability problem second. Two things make this fleet shippable to production without hand-rolling guardrails: - **Audit-grade observability**. Every tool call is captured as append-only JSONL. Failures additionally capture the full upstream HTTP trail — every request, every retry, every response — with secrets redacted at the source. Query it directly in BigQuery for hosted deployments, or pipe stdout to your existing log stack for self-host. [Read the observability guide](docs/guides/observability.md). - **Destructive-action elicitation gates**. 51 destructive tools across the twelve write-capable servers (`dbm-mcp` is reporting-only) prompt the user before deletes, bulk status changes, bid adjustments, budget changes, conversion uploads, and async Workflows batch jobs. Stdio and clients without elicitation support fall back to a documented non-interactive contract. Bulk mutations under 10 items skip the prompt unless they touch a sensitive field (status / budget / bid). - **Verifiable release provenance**. Governed tools carry a canonical SHA-256 `definitionHash` (from `@cesteral/contract-hash`) emitted into a per-package `cesteral-manifest.json`. Tagged releases publish to npm with build provenance, signing the manifest transitively inside the tarball, so a downstream governance system can verify exactly which tool definitions shipped and promote matching tools to `attested` trust. If your security review needs evidence — the redaction list, the field schema, the upstream capture path, the contract hash — all of it is in this repository. --- ## Quick Start For a guided walkthrough, see the [10-minute quickstart](docs/guides/quickstart.md). ### Prerequisites - **Node.js** >= 20.0.0 - **pnpm** >= 10.0.0 -- `corepack enable` picks up the pinned version from `packageManager` (or `npm install -g pnpm@10`) - **Docker** (for containerization) - **Terraform** >= 1.6.0 _(for deployment)_ ### 1. Clone and install ```bash git clone https://github.com/cesteral/mcp-open-advertising.git cd mcp-open-advertising pnpm install ``` ### 2. Build ```bash pnpm run build ``` ### 3. Run a server locally ```bash # Start any server using the dev script ./scripts/dev-server.sh gads-mcp # port 3004 ./scripts/dev-server.sh meta-mcp # port 3005 ./scripts/dev-server.sh dv360-mcp # port 3002 # See each package README for required environment variables ``` ### 4. Configure your AI agent ```json { "mcpServers": { "cesteral-gads": { "url": "https://gads.your-domain.com/mcp", "apiKey": "your-gads-api-key" }, "cesteral-meta": { "url": "https://meta.your-domain.com/mcp", "apiKey": "your-meta-api-key" } } } ``` Add as many servers as you need. Each runs independently and can be deployed separately. ### 5. Deploy ```bash cd terraform terraform init terraform apply -var-file=dev.tfvars ``` See the [deployment guide](docs/guides/deployment-instructions.md) for production setup. --- ## Architecture Cesteral uses a **GCP-native architecture** with thirteen independently deployable Cloud Run MCP services. Each server exposes the MCP protocol directly via HTTPS on Cloud Run. **Key design decisions:** - **Single cloud provider (GCP)**: Cloud Run, BigQuery, Pub/Sub, Secret Manager -- unified monitoring, ~$150-220/month - **Direct HTTP transport**: No edge gateway layer needed - **Independent deployment**: Each server can be deployed and scaled separately - **Composable**: Use one server or all thirteen -- they work independently or together AI clients connect directly to one or more MCP servers over HTTPS; there is no shared gateway to provision. Cesteral Intelligence, when used, layers tenancy, credentials, approvals, and governance above the same fleet. ### Repository Structure ``` mcp-open-advertising/ ├── packages/ │ ├── gads-mcp/ # Google Ads │ ├── meta-mcp/ # Meta Ads │ ├── dv360-mcp/ # DV360 │ ├── ttd-mcp/ # The Trade Desk │ ├── linkedin-mcp/ # LinkedIn Ads │ ├── tiktok-mcp/ # TikTok Ads │ ├── cm360-mcp/ # Campaign Manager 360 │ ├── sa360-mcp/ # Search Ads 360 │ ├── pinterest-mcp/ # Pinterest Ads │ ├── snapchat-mcp/ # Snapchat Ads │ ├── amazon-dsp-mcp/ # Amazon DSP │ ├── msads-mcp/ # Microsoft Ads │ ├── dbm-mcp/ # Bid Manager (reporting) │ ├── contract-schema/ # Shared library -- canonical annotation + response schemas │ ├── contract-hash/ # Shared library -- canonical tool-definition hash │ └── shared/ # Shared auth, telemetry, utilities ├── terraform/ # Infrastructure as Code ├── scripts/ # Deployment and dev automation └── docs/ # Documentation and guides ``` --- ## Development ```bash # Install dependencies pnpm install # Build all packages pnpm run build # Run tests pnpm run test # Type checking pnpm run typecheck # Lint pnpm run lint ``` ### Testing MCP Tools ```bash # Use MCP Inspector npx @modelcontextprotocol/inspector packages/gads-mcp # Or use curl curl -X POST http://localhost:3004/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}' ``` ### Technology Stack - **Runtime**: TypeScript 5.0+, Node.js 22 LTS, Hono (HTTP + MCP transport) - **Validation**: Zod schemas - **Infrastructure**: GCP Cloud Run, BigQuery, Pub/Sub, Secret Manager, Terraform - **Build**: Turborepo, pnpm workspaces, Docker --- ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. 1. Fork the repository 2. Create a feature branch: `git checkout -b feature/your-feature` 3. Make changes and write tests 4. Run tests: `pnpm run test` 5. Submit a Pull Request See also: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | [SECURITY.md](SECURITY.md) | [ROADMAP.md](ROADMAP.md) --- ## License [Apache License 2.0](LICENSE.md) --- ## Support - **Website**: [cesteral.com](https://cesteral.com) -- managed hosting and commercial features - **Documentation**: [docs/](docs/) for guides and architecture - **GitHub Issues**: Report bugs or request features - **Email**: support@cesteral.com