Ad Campaign MCP
This MCP server exposes two read-only tools for querying advertising campaigns from a REST API backed by Postgres.
List all campaigns or filter by status (
active,paused, ordraft) vialist_campaigns.Fetch a single campaign by its
idviaget_campaign.Return error results (not exceptions) for a 404 or an unreachable API.
Handle API key authentication automatically when calling the REST API.
No create/update/delete tools; campaigns must be seeded directly via SQL.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Ad Campaign MCP What are my active ad campaigns?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ad Campaign MCP
An MCP (Model Context Protocol) client/server integration built with TypeScript/Node.js. It connects an AI assistant to a small REST API over structured, typed tools — with real error handling for a down API or a missing record — rather than the assistant calling the API directly.
Architecture
MCP client (AI assistant)
│ stdio, JSON-RPC
▼
MCP server (src/index.ts)
│ HTTP
▼
Campaign REST API (src/api.ts, Express)
│ SQL
▼
Postgres (docker-compose.yml)Postgres —
advertisers,campaigns,impressions, andclickstables, created on API startup bysrc/db.ts.REST API (
src/api.ts) —GET /campaigns(optionally filtered by?status=) andGET /campaigns/:id, backed by Postgres.MCP server (
src/index.ts) — exposes two tools that call the REST API and translate its responses (including non-2xx statuses and connection failures) into MCP tool results.
Related MCP server: Ads Analytics MCP
Getting started
cp .env.example .env # then set DB_PASSWORD and API_KEY (openssl rand -hex 32)
docker compose up -d # start Postgres
npm install
npm run api # start the REST API on :3000
npm run build # compile the MCP server to dist/Run the MCP server directly during development with npm run dev (uses
tsx, no build step needed), or run the compiled version with
node dist/index.js. The compiled version starts noticeably faster,
since it skips on-the-fly TypeScript transpilation — worth using for an
MCP client that spawns the server, since Client.connect() has a
default 60s handshake timeout.
All configuration lives in .env (git-ignored; see .env.example).
src/config.ts loads it relative to the project root, so it is found
even when an MCP client spawns the server from another directory. The
API URL defaults to http://localhost:3000; override it with
API_BASE_URL if the REST API runs elsewhere.
Every REST API request must send the x-api-key header matching
API_KEY; the MCP server does this automatically. Postgres and the API
listen on 127.0.0.1 only.
Sample API calls
There's no POST /campaigns endpoint yet, so the table starts empty —
seed a row directly via SQL first, or the calls below just return []
/ 404.
Seed a campaign (direct SQL)
docker exec -it ad-campaign-postgres psql -U "$DB_USER" -d adplatform -c "
INSERT INTO advertisers (name) VALUES ('Acme Corp') RETURNING id;
-- suppose that returns id = 1
INSERT INTO campaigns (id, advertiser_id, name, status, budget, start_date, end_date)
VALUES ('camp_001', 1, 'Summer Launch', 'active', 5000.00, '2026-06-01', '2026-08-31');
"GET /campaigns — list all
source .env # makes $API_KEY available in this shell
curl -H "x-api-key: $API_KEY" http://localhost:3000/campaigns[
{
"id": "camp_001",
"advertiser_id": 1,
"name": "Summer Launch",
"status": "active",
"budget": "5000.00",
"start_date": "2026-06-01T00:00:00.000Z",
"end_date": "2026-08-31T00:00:00.000Z",
"created_at": "2026-08-29T10:00:00.000Z",
"updated_at": "2026-08-29T10:00:00.000Z"
}
]GET /campaigns?status=active — filtered by status
curl -H "x-api-key: $API_KEY" "http://localhost:3000/campaigns?status=active"GET /campaigns/:id — single campaign
curl -H "x-api-key: $API_KEY" http://localhost:3000/campaigns/camp_001Returns the same object as above, unwrapped from the array.
GET /campaigns/:id — not found
curl -i -H "x-api-key: $API_KEY" http://localhost:3000/campaigns/does-not-existHTTP/1.1 404 Not Found
{"error":"Campaign not found"}Tools exposed
list_campaigns— list campaigns, optionally filtered bystatus(active|paused|draft).get_campaign— fetch a single campaign byid; returns an error result (not a thrown exception) for a 404 or an unreachable API.
Trying it end-to-end
npm run build
node demo-mcp-client.mjsThis spawns the compiled MCP server, performs the MCP handshake, lists its tools, and calls each one — including the 404 case — printing the results.
Known limitations
Authentication is a single shared API key — fine for local use.
No
POST/PUTendpoints yet — campaigns can only be seeded directly via SQL, not created through the API or the MCP tools.
License
MIT
Available Tools
2 toolsget_campaignB
Get a single advertising campaign by id
Inputs: id (required).
list_campaignsC
List advertising campaigns
Inputs: status.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools have clearly distinct purposes: one lists all campaigns and the other retrieves a single campaign by id. There is no ambiguity or overlap between them.
Both tool names follow the consistent verb_noun pattern (list_campaigns, get_campaign), making the naming predictable and easy to understand.
With only two tools, the server feels thin for a domain like ad campaigns, which typically involves more than just reading. However, the count is acceptable if the server is intentionally scoped to read-only operations.
The tool surface only covers listing and retrieving campaigns; there is no create, update, or delete functionality. This is a significant gap for an ad campaign management server, leaving agents unable to perform any lifecycle actions.
Maintenance
Related MCP Connectors
Marketing intelligence API for AI agents. Real campaign data, not LLM guesses.
Amazon Ads and Seller Central for your AI assistant: reports, campaign management and seller data.
Real-time Meta, Google, LinkedIn and TikTok ad library access for AI assistants. No API keys.
Build, edit and sync Google, Microsoft, Reddit and Meta ad campaigns from your assistant.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables users to manage Uber advertising campaigns through natural language by providing access to Uber's External Ads API. Supports campaign creation, retrieval, updating, and deletion with comprehensive filtering and configuration options.5-
- AlicenseAqualityDmaintenanceProvides read access to campaign performance data from Google Ads, Meta Ads, and TikTok Ads via live API calls, enabling AI assistants to analyze and audit advertising campaigns.162MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with the Amazon Advertising API to manage campaigns, keywords, product ads, and retrieve performance metrics.952 npm3MIT

ictcontact-mcpofficial
AlicenseBqualityBmaintenanceEnables AI assistants to monitor outbound campaigns in ICTContact/ICTDialer, including listing campaigns, checking status, reading summaries and per-call results, and optionally starting and stopping campaigns when write access is enabled.443 npm16MIT