servicehawk-ad-intel
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., "@servicehawk-ad-intel Record this plumber ad swipe: free drain inspection offer, headline 'Drains slow?'"
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.
ServiceHawk Ad Intel MCP
An MCP server for building a competitive ad swipe file from public Meta Ads Library research, for ServiceHawk, an agency that sells automation to home service businesses (plumbers, HVAC, pest control, roofers, electricians).
It is not a bot for logging into Meta, scraping past a paywall, or bypassing rate limits. It does none of that, on purpose:
No credentials, ever. It has no login flow and cannot be given one.
No fetching outside a small host allowlist (facebook.com, www.facebook.com, m.facebook.com, transparency.meta.com by default).
No destructive tools. Every write goes to a local append-only file.
No cloning. The scoring tools grade a pattern's reusable structure (hook, offer, proof, format); the copy generator writes new lines from that structure, never a competitor's actual sentence.
What it is: a small, honest tool for turning public ad research into a scored, searchable swipe file, plus a generator that drafts new ServiceHawk ad copy from the angles that keep showing up as winners.
Why this exists
Meta's official Ad Library API only really covers social issue, election, and politics ads worldwide, plus all ad types for the UK and EU over the past year. For ordinary US commercial competitor research, that leaves the public Ad Library web UI and manually saved pages, not a clean API you can query in bulk. This server is built around that constraint instead of pretending it does not exist: it helps you build the right search URLs, captures a public page when one is reachable without login, and gives you a structured way to record what you saw by hand when it is not.
Related MCP server: Facebook Ads Library MCP Server
Install
cd servicehawk-ad-intel-mcp
npm install
npm run smoke
npm run smoke:mcpnpm run smoke exercises the scoring and storage logic directly.
npm run smoke:mcp spins up the server over stdio and calls it as a real
MCP client would, so both checks run against the actual code path, not a
mock.
Run
node /path/to/servicehawk-ad-intel-mcp/src/server.jsIt speaks MCP over stdio, so in practice you point an MCP client at it instead of running it by hand. Example client config:
{
"mcpServers": {
"servicehawk-ad-intel": {
"command": "node",
"args": ["/path/to/servicehawk-ad-intel-mcp/src/server.js"]
}
}
}Any MCP-capable client (Claude Code, Claude Desktop, or your own MCP client built on the SDK) can load it this way. The server has one job: expose the tools below over stdio. It does not manage its own client connection or UI.
Tools
Tool | Takes | Returns |
| Optional |
|
|
|
|
|
|
|
| Same ad fields as above, without saving |
|
| Optional |
|
| Optional |
|
|
|
|
score_ad_pattern rewards signals that predict a reusable pattern: how long
an ad has run, how many similar variants exist, whether the copy lands on a
home-service pain point, whether the offer is a low-friction diagnostic
(free audit, free report), and whether the headline is short enough to read
in a feed scroll. It penalizes risky claims (guarantees, "#1", platform
trademarks in the copy) and bloated primary text. The score is a signal for
prioritizing research, not a prediction of CPA or ROAS, and the tool says so
in its own output.
Data
Everything is stored locally as flat files, not a database:
data/swipes.jsonl one recorded ad observation per line
data/captures/*.json saved public-page capturesOverride the location with AD_INTEL_DATA_DIR. See .env.example.
Safety
No credentials anywhere in this server or its config.
No logged-in scraping and no bypassing of Meta's own blocks. If a page comes back blocked, the tool says so and tells you to capture it by hand.
No arbitrary URL fetching.
capture_public_ad_pagechecks the hostname against an allowlist before it makes a request, full stop.Every write is append-only to a local file. Nothing here deletes or overwrites past research.
Approach
This server ships with a written contract for every tool: what it takes, what it returns, and what it explicitly refuses to do (see Safety, above). Getting that contract right did not come from one pass at the code.
The work was split across roles that each owned one narrow piece of it
(the tool contracts, the scoring rules, the safety constraints) instead of
one generalist trying to hold the whole thing in its head at once. A
separate, independent pass then checked the result against the actual
source code rather than trusting the first answer, and a set of
deterministic checks, not a model's own say-so, decided what was safe to
publish. That is the same standard applied to every claim in this README:
the tool list, the input contracts, and the safety behavior above were
verified against src/lib.js and src/server.js, not written from memory.
Layout
Path | What |
| MCP server: registers the tools above and wires each one to |
| The actual logic: URL building, allowlisted fetch, scoring, and swipe file storage |
| Exercises the scoring and storage logic directly, no MCP layer |
| Spawns the server and calls it as a real MCP client, over stdio |
Limits
The scoring model is a fixed set of hand-written rules, not a trained model. It rewards home-service and diagnostic-offer signals specifically, not general ad quality, so a strong score in a different vertical means less.
Meta can and does block automated fetches of Ad Library pages. When that happens the right move is manual capture into
record_ad_swipe, not a workaround, and this server does not try to build one.capture_public_ad_pageonly extracts text; it does not download images or video, and it does not render JavaScript.
About
Built by Roderick Finch, ServiceHawk AI (servicehawkai.com), Pembroke Pines, FL.
MIT licensed.
Available Tools
7 toolsbuild_meta_ad_library_urlA
Create a public Meta Ads Library search URL for manual competitive ad research.
Inputs: query, ad_type, country, page_id, +2 more.
capture_public_ad_pageA
Fetch and store metadata/text from an allowlisted public ad-library page without login or bypass behavior.
Inputs: url (required), timeout_ms, max_text_chars.
generate_servicehawk_variantsB
Generate ServiceHawk-safe Meta still-image ad copy variants from known winning angle families.
Inputs: cta, angle.
list_ad_swipesB
List stored ad swipe observations filtered by vertical, offer, and minimum score.
Inputs: limit, offer, vertical, min_score.
record_ad_swipeA
Record one observed ad pattern into the local swipe file and score its reusable winning signals.
Inputs: offer (required), headline (required), page_name (required), visual_notes (required), +11 more.
score_ad_patternA
Score a copied ad pattern for reusable winning signals without saving it.
Inputs: offer (required), headline (required), visual_notes (required), format, +7 more.
summarize_winning_patternsC
Summarize top stored swipe patterns and recommend ServiceHawk remix angles.
Inputs: top, min_score.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct step in the ad research workflow: generating variants, building search URLs, capturing pages, scoring/recording patterns, listing, and summarizing. The only mild overlap is between generate_servicehawk_variants and summarize_winning_patterns, but their inputs and outputs are clearly different enough.
All tool names follow a predictable snake_case verb_noun pattern: generate_, build_, capture_, record_, score_, list_, summarize_. This makes the tool set easy to navigate and mentally model.
Seven tools is well-scoped for an ad intelligence server, covering generation, capture, evaluation, storage, retrieval, and synthesis without unnecessary duplication. Each tool earns its place in the workflow.
The core ad-research lifecycle is covered: capture, score, record, list, and summarize. The main gap is the lack of update/delete operations for stored swipes, but agents can still complete the primary workflow without them.
Maintenance
Related MCP Connectors
Track competitors' Meta ads, save swipe files and run Meta campaigns from Claude, ChatGPT or Cursor.
Search a library of winning Meta ads and remake them in your brand, or make new ones.
Real-time Meta, Google, LinkedIn and TikTok ad library access for AI assistants. No API keys.
Ad library and ad spy for AI agents: winning Facebook and Instagram ads, competitor ads and hooks.
Related MCP Servers
AlicenseBqualityCmaintenanceSee who is running ads in your space, clone a winning ad for your brand as an image or video, and launch it on Meta, Google, TikTok, X, or ChatGPT Ads. The full research, clone, launch loop from one chat in Claude, ChatGPT, or Cursor. Flat pricing, no fabricated metrics.4730 npmMIT- AlicenseAqualityBmaintenanceEnables searching and analyzing Facebook's public ads library for any brand, including ad images, text, and video analysis.823 npm332MIT
- AlicenseNot gradedqualityCmaintenanceEnables searching and scraping the public Facebook Ad Library to extract structured ad data such as advertiser, copy, landing URLs, and CTAs for competitive research, all without an account or API token.MIT
- AlicenseNot gradedqualityBmaintenanceEnables searching Meta ads by text, country, category, advertiser, or landing domain from an AI assistant, then opening individual ads and advertiser pages, ranking what is scaling, finding related ads by page or domain, and downloading images and videos for ad ids.1MIT