Adwarp

Adwarp

Website · Docs · Install guide · npm package

Adwarp (formerly Liam) is the open-source ad agent for LinkedIn Ads and Google Ads. Create campaigns by talking to Claude (MCP) or from a CLI. Built for go-to-market teams who want to spin up many campaigns from a contact list and a brief, then add creative images themselves. Everything starts switched off: LinkedIn entities are created as drafts and Google entities as paused. A LinkedIn campaign goes live only when you explicitly ask Adwarp to turn it on or switch it on yourself in Campaign Manager, and Google campaigns can only be switched on in the Google Ads UI.

Unofficial and not affiliated with or endorsed by LinkedIn or Google.

Covers creation, matched audiences (including building one straight from Salesforce or HubSpot),

conversion selection, performance reporting/insights, competitor ad intelligence, and a

change journal with before/after lift. See ROADMAP.md for what's shipped

and what's planned next.

What you can do with it

Once Adwarp is connected, you talk to your assistant in plain language. Real requests it handles today, roughly in the order a campaign comes together:

• "How many VPs of demand gen at US SaaS companies can we reach?" (resolves targeting facets, estimates reach before any money is involved)
• "Upload this CSV as a matched audience." (auto-cleans columns, hashes emails, keeps names, companies and titles for LinkedIn's people match, converts company domains to URLs)
• "Build an audience from Salesforce: every contact on an account flagged as a target." (SOQL straight to a matched audience)
• "Turn our HubSpot target accounts list into a LinkedIn audience." (a HubSpot list or search straight to a matched audience of contacts or companies)
• "Launch a draft campaign for that audience, $100/day, tracking the demo-booked conversion." (campaign group + campaign + draft ads in one call)
• "What ads is our biggest competitor running right now, and what offers are they pushing?" (reads the public Ad Library: copy, formats, and EU targeting metadata for any company)
• "How did retargeting do last month vs the month before?" (trend report with deltas)
• "Which ads should I pause this week?" (account rollup with top/bottom performers and flags, then pauses the ads you pick, leaving the rest of each ad group running)
• "Rewrite the copy on the losing ad." (delete + recreate as a fresh draft; LinkedIn ignores edits to a live ad's post)
• "Did the new headline actually help?" (change journal + before/after lift)

Adwarp resolves the details and reports back the ids. Every capability is also an adwarp CLI command for scripted or batch use.

Put it on a loop

There is no scheduler in Adwarp. Use the one in whatever client you drive it from. Some loops that work well:

• "Every Monday at 9am, pull last week's performance summary, compare it to the week before, and flag anything that moved more than 20%." (a Claude Code scheduled agent)
• "Every Friday, check what new ads our top three competitors shipped this week and summarize the angles."
• "Check the audience match status every few hours and tell me when it clears 300 members." (the minimum for a matched audience to serve)
• Or skip the assistant entirely and put the CLI in cron: 0 9 * * 1 adwarp report summary -p last_7_days

Hierarchy mapping (the two platforms disagree)

LinkedIn's names are shifted one level from everyone else's, which is the single most common source of confusion when working across both:

So a LinkedIn "campaign" and a Google "campaign" are not the same thing: Google's campaign holds the budget and targeting (LinkedIn's *campaign group* plus *campaign*), and its ad group holds keywords.

Google Ads

Search campaigns only, creation-first. What is there today:

adwarp google auth login

adwarp google accounts list # proves the token and OAuth client work adwarp google keywords "revops automation" --url https://example.com/product adwarp google conversions list adwarp google launch --brief examples/google-brief.json # dry run adwarp google launch --brief examples/google-brief.json --apply # create it, paused adwarp google campaigns list adwarp google report perf keyword -p last_30_days

A launch creates the budget, campaign, geo and language targeting, ad groups, keywords, and responsive search ads in one atomic mutate: it either lands whole or not at all, so a failure cannot leave half a campaign behind. Every write is validated server-side first, which is a genuine dry run rather than a local guess.

Three house rules are hard-coded, because all three default the wrong way in the UI and quietly waste B2B budget:

• Search network only. Display expansion and search partners off.
• Physical presence only. "US" means people in the US, not people anywhere who searched about it.
• Manual CPC to start. Smart bidding with no conversion history spends unpredictably. Switch in the UI once there is data.

Setup

Google Ads needs two things LinkedIn does not:

1. A developer token, from a Google Ads manager (MCC) account at ads.google.com/aw/apicenter. A plain client account cannot issue one. Approval usually lands on Explorer access automatically (2,880 production ops/day).

Explorer is not enough for `adwarp google keywords`. Explorer blocks KeywordPlanService, so keyword research needs Basic access (15,000 ops/day), which is a separate application on the same screen. Campaign creation and reporting work fine on Explorer.

1. An OAuth client, from a Google Cloud project with the Google Ads API enabled. Use the "Desktop app" type, which accepts any localhost redirect.

For the consent screen, do not leave it in "Testing". That status issues refresh tokens that stop working after 7 days. Beyond that it is a trade:

• Internal (Workspace orgs only) is what Google's OAuth docs recommend for a single-company tool. Simplest, no verification, no 7-day expiry.
• External + In production is the precondition for *brand verification*, the pilot that cuts Basic Access review from days to hours. The cost is that auth/adwords is a sensitive scope, so a published external app can require full OAuth app verification, potentially slower than the wait it saves.

Internal is the better default for an internal tool. Choose External only if the fast track is worth the verification risk.

Then write ~/.adwarp/google.json:

{

"clientId": "....apps.googleusercontent.com", "clientSecret": "...", "developerToken": "...", "loginCustomerId": "1234567890", "defaultCustomerId": "0987654321", "defaultConversionActionNames": ["Demo Booked"] }

loginCustomerId is the manager account and is only needed when you reach the target account through one. Run adwarp google auth login and you are set. Set up Google Ads in the docs has the same steps, plus the ADWARP_GOOGLE_* environment variables.

Packages

• @adwarp/shared: the platform-neutral layer: OAuth, credential stores, retry policy, the change journal, period and KPI math.
• @adwarp/core: LinkedIn REST client, resource modules, CSV + SHA256 hashing, Salesforce and HubSpot readers.
• @adwarp/google: Google Ads REST client, GAQL reads, atomic mutate builder, Search campaign creation.
• @adwarp/mcp: MCP server (stdio for local; reused by the hosted app). Primary interface.
• @adwarp/cli: the adwarp CLI over the same engines, for scripted batch runs.
• @adwarp/web: Next.js app that hosts the MCP over HTTP on Vercel, at https://mcp.adwarp.dev/api/mcp. It serves no pages: its other paths redirect to adwarp.dev.
• adwarp: the published npm package. Bundles the CLI and the MCP server behind the adwarp, adwarp-mcp and liam commands.

How it works

Both interfaces are thin layers over the same engine. Every MCP tool and CLI command builds a client via createLinkedInAds() (core/src/client.ts), which loads config plus an auto-refreshing OAuth token provider, then calls a typed resource module (campaigns.ts, audience.ts, report.ts, ...) that wraps LinkedIn's versioned REST API (LinkedIn-Version pinned in config). Input shapes live as zod schemas in core/src/schemas.ts and are reused verbatim as the MCP tool input schemas, so the CLI and MCP can never drift apart.

The drafts-first safety rule is enforced at creation: campaign groups, campaigns, and creatives default to DRAFT status, and going live is always an explicit request (a status of ACTIVE, campaigns update --status ACTIVE --apply, or ad resume --apply). On Google, no create schema can express an enabled status at all. Every write also passes through one HTTP chokepoint that appends to a local change journal (~/.adwarp/changelog.jsonl) for later lift analysis.

AGENTS.md has the full architecture notes and the LinkedIn API gotchas (restli encoding, required fields, DMP audience flow) learned from live testing.

Install

The install guide on adwarp.dev has these steps too, with a setup page for each client: Claude Code, Claude Desktop, Cursor, Codex, Gemini, the CLI, and, through your own endpoint, Meta Muse and Grok Bot.

There are two ways to install Adwarp:

1. [As an MCP server](#option-1-install-as-an-mcp-server), registered with Claude Code, Claude Desktop, Cursor, Codex, or other MCP clients that can run a local server, so you create campaigns by talking to your assistant. Run it locally, or skip the always-on install entirely and connect to the hosted endpoint with your own credentials.
2. [As a terminal CLI](#option-2-install-the-terminal-cli), a global adwarp command for running everything from your terminal, scripts, or cron.

Both run against your own LinkedIn developer app, so your credentials and your ad account stay yours. Both come from the same npm package, adwarp. The first two steps are shared: create a LinkedIn app (step 0) and authenticate (step 1). After that, pick your path, or do both; they read the same ~/.adwarp credentials.

Step 0: create a LinkedIn app (once)

1. Create an app at https://www.linkedin.com/developers/apps. It must be associated with your company's LinkedIn Page.
2. On the Products tab, request access:

| Product | Needed for | Required?