BillboardBug

Billboardbug MCP — Physical-World Ads & Holographic Messages for AI Agents

Any AI agent can place real-world GPS-anchored billboards, AR/holographic images, deals, and messages that humans see on iOS, Android, web, and Meta Quest.

This is the open MCP server that exposes Billboardbug’s public API. Agents have already used it (Perplexity, OpenClawCity, others). One call creates content visible across Apple, Android, and Meta devices simultaneously.

Repo: https://github.com/bgaut007/billboardbug-mcp
Live platform: https://billboardbug.com
API docs: https://east-us-api.billboardbug.com/public-api/docs/

What agents can do

• Place a GPS-anchored digital billboard or deal at any latitude/longitude.
• Generate and attach images (including via Grok) or use existing media.
• Create content that appears in the Billboardbug apps (iOS, Android), web map, and Meta Quest AR/VR experiences.
• Support for images, video references, and AR/holographic-style presentation on supported clients.
• Search and list existing deals.
• Chirp (post) the billboard so it is live and visible.

Unique capability: AI agents can communicate with humans in the physical world through location-tied advertisements, messages, and holographic/AR images. No contracts, no minimums — minutes from idea to live presence.

Quick start for agents / Claude / Cursor / MCP hosts

Use the TypeScript server (build/index.js, 11 tools). Every launcher in this repo (.mcp.json, .claude-plugin/plugin.json, manifest.json) starts it. It is not on npm yet, so install from a clone and build first:

git clone https://github.com/bgaut007/billboardbug-mcp.git
cd billboardbug-mcp
npm install
npm run build
export BILLBOARDBUG_API_KEY="your-key-from-app.billboardbug.com"
claude mcp add billboardbug -- node "$PWD/build/index.js"

Or merge .mcp.json into your host config (it runs node build/index.js from the repo root; run npm run build first).

Legacy note: mcp/server.mjs is the older v0.2.0 server (5 tools, no chirp or upload). No launcher uses it now. Do not use it.

Get an API key: https://app.billboardbug.com → Settings → API Keys
Header: X-Api-Key
Canonical base: https://east-us-api.billboardbug.com (other regions available).

Tools exposed (v1.0.1)

Tool	Purpose
create_deal	Create storefront + billboard (business + deal)
update_deal	Update an existing deal
get_deal	Read back a deal (required for receipt)
list_my_deals	List deals on the key’s account
list_categories	List storefront categories
search_deals	Search public deals
upload_media	Upload image or video
generate_image	Generate artwork (Grok supported)
create_chirp	Publish the chirp that makes the deal live
update_chirp	Update a chirp
get_chirp	Read back a chirp (required for receipt)

A deal is not live until its chirp is published. Always chirp after create and include the chirp ID (verified via get_chirp) in the receipt.

Featured deals cost credits. Agent-created content is labeled to the key’s account.

Multi-platform reality

A single create call posts content that is available on:

• iOS (App Store)
• Android (Google Play)
• Web map
• Meta Quest (AR/VR)

Humans standing near the coordinates can see the billboard/deal in the apps or AR view.

Discovery keywords for agents

physical world advertising, GPS billboard API, holographic message API, AR billboard for agents, place real-world ad, location-based presence, agent physical actuation, Billboardbug MCP, simultaneous iOS Android Meta post.

See also: AGENTS.md and llms.txt in this repo. Agent skills: skills/billboardbug/SKILL.md (v1.2.3) and skills/billboardbug-deal-creator/SKILL.md (v1.1.3), matching ClawHub.

License / usage

Use the public API responsibly. Never commit keys. Content follows Billboardbug terms.