whooshly mcp

Whooshly MCP

Give your AI assistant a campaign-link toolkit. Whooshly exposes a hosted Model Context Protocol server so Claude, ChatGPT, and any MCP client can create short links, dynamic QR codes, UTM templates, hosted vCard pages, and landing pages with lead capture – and read back real click/scan analytics – directly from a conversation.

"Shorten this launch URL, make a QR for the flyer, and save a UTM template for the paid-social campaign" → three tools, one message, links you actually own.

• 🔗 Short links on whooshly.co with live click tracking
• 🟧 Dynamic QR codes returned as scannable PNGs, right in the chat
• 🏷️ UTM templates you can reuse across campaigns
• 📇 Hosted vCard digital business cards
• 📊 Real analytics – exact click/scan totals and daily series per link
• 💸 Pay once. Unlock the core toolkit for a one-time price – no subscription. See pricing →

The server is hosted – there's nothing to run for URL-based clients. This npm package is a small stdio bridge for clients that don't yet speak remote MCP (e.g. Claude Desktop) and for npx convenience.

---

1. Get an agent token

Every tool acts on your Whooshly account, so you need a token:

1. Sign in at app.whooshly.co
2. Open Agents → New token
3. Copy the token (shown once)

Reads and writes require the one-time Core unlock; get_billing_status works on any account so an agent can check before it acts.

---

2. Connect

Claude.ai / Claude (web, desktop, mobile) – by URL, no install

Add a Custom Connector pointing at the remote server. Claude runs the OAuth flow in-browser; approve it and the tools appear.

https://app.whooshly.co/api/mcp

Settings → Connectors → Add custom connector → paste the URL.

ChatGPT – by URL

Add a connector / custom MCP server with the same URL:

https://app.whooshly.co/api/mcp

Claude Code – one command

claude mcp add whooshly --transport http https://app.whooshly.co/api/mcp

Then authenticate with /mcp inside Claude Code, or pass a token header:

claude mcp add whooshly --transport http https://app.whooshly.co/api/mcp \
  --header "Authorization: Bearer $WHOOSHLY_TOKEN"

Claude Desktop (or any stdio client) – via this bridge

For clients that only speak stdio, use this package. Add it to your claude_desktop_config.json:

{
  "mcpServers": {
    "whooshly": {
      "command": "npx",
      "args": ["-y", "whooshly-mcp"],
      "env": {
        "WHOOSHLY_TOKEN": "your-agent-token"
      }
    }
  }
}

That's it – restart the client and the Whooshly tools are available.

---

Tools

Tool	What it does	Access
get_billing_status	Check whether the account has unlocked Core / Pro	any
create_link	Create a short link → id, slug, short URL	Core
list_links	List your links, newest first (cursor-paged)	Core
get_link_stats	Exact click/scan totals + daily series for a link	Core
create_qr	Create a dynamic QR code, returned as a scannable PNG	Core
get_qr	Re-fetch a saved QR code as a PNG	Core
create_utm	Save a reusable UTM template	Core
list_utm	List saved UTM templates	Core
create_vcard	Create a hosted digital business card (vCard) page	Core
create_page	Create a landing page on your subdomain from content blocks	Core
update_page	Edit a page's blocks, theme, or slug – never deletes	Core
list_pages	List your landing pages with lead counts	Core
get_page	One page's content, lead count & webhook delivery rollup	Core
search	Search your links by slug/destination (deep-research)	Core
fetch	Fetch full details of one link by id (deep-research)	Core

All read tools are annotated readOnlyHint; write tools can only create or edit – an agent can never delete anything, never read your leads' personal details (counts only), and never see or change a lead webhook. Every tool operates only on your own account (openWorldHint: false).

---

Example prompts

Once connected, try:

• "Shorten https://example.com/2026-summer-launch with the slug summer26 and show me the QR code."
• "Create a UTM template called paid-social with source instagram, medium cpc, campaign summer-launch."
• "How many clicks did my summer26 link get this week?"
• "Make a vCard for Jane Doe, Head of Growth at Acme, jane@acme.com."

---

Configuration

Env var	Default	Purpose
WHOOSHLY_TOKEN	–	Required for the stdio bridge. Your agent token.
WHOOSHLY_MCP_URL	https://app.whooshly.co/api/mcp	Override the endpoint (self-host / staging).

WHOOSHLY_API_TOKEN is accepted as an alias for WHOOSHLY_TOKEN.

---

How the bridge works

whooshly-mcp reads newline-delimited JSON-RPC from stdin, POSTs each message to the hosted server with your bearer token, and writes the correlated reply to stdout. It has zero npm dependencies (Node 18+ built-ins only), so it's small and easy to audit – the entire bridge is one file: bin/whooshly-mcp.mjs.

The heavy lifting – auth, rate limits, entitlement checks, QR rendering, analytics – all happens server-side on Whooshly. The bridge is a transport shim, nothing more.

---

Links

• Website: https://whooshly.co
• MCP server / connect guide: https://whooshly.co/mcp
• App / dashboard: https://app.whooshly.co
• MCP endpoint: https://app.whooshly.co/api/mcp

License

MIT © Whooshly