MCP Tools Reference

A concise, skimmable catalog of Bitly MCP tools.

Link Management

bitly_create_short_link - Create a compact, shareable link with advanced customization options

Parameters:

long_url (optional; required if bitlink_id not provided)
bitlink_id (optional; existing short link to add a custom back-half to)
domain (optional)
group_guid (optional)
title (optional)
tags (optional; string[])
keyword (optional; custom back-half for the short link)
dynamic_routing (optional; object[]; up to 10 rules; send visitors to different destinations by country, region, device, or OS)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Shorten https://example.com/very-long-product-page-url"

"Create a short link for https://example.com/spring-sale titled 'Spring Sale 2024' tagged 'marketing' and 'seasonal' using our custom domain"

"Create a custom short link bit.ly/summer-sale for https://example.com/sale"

bitly_create_short_link_with_qr - Create a short link and a QR Code that encodes it in a single step (one approval covers both)

Parameters:

group_guid (required)
bitlink_id (optional; existing short link to encode; required if long_url not provided)
long_url (optional; required if bitlink_id not provided)
domain (optional)
title (optional; used for the short link)
tags (optional; string[])
keyword (optional; custom back-half for the short link)
dynamic_routing (optional; object[]; up to 10 rules; applied to the short link)
qr_title (optional; defaults to the link title when omitted)
archived (optional; boolean)
render_customizations (optional; object; QR appearance)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Create a short link and matching QR Code for https://example.com/event in my marketing group"

"Make bit.ly/summer-sale for https://example.com/sale and generate a QR Code titled 'Summer Sale Flyer'"

bitly_get_short_link_details - Get complete short link details (title, destination, created, creator, tags, custom domains)

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show me the full details for bit.ly/ABC123"

bitly_update_short_link - Update destination URL, title, archive state, tags, or dynamic routing rules

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
long_url (optional)
title (optional)
archived (optional; boolean)
tags (optional; string[])
dynamic_routing (optional; object[]; up to 10 rules; replaces all existing rules, pass [] to remove them)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Archive bit.ly/ABC123"

"Update bit.ly/ABC123 with title 'Updated Campaign Link' and tags 'Q1-2024' and 'email-campaign'"

"Change the destination of bit.ly/ABC123 to https://example.com/new-page"

bitly_delete_short_link - Permanently delete a short link (unedited links only)

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
response_format (optional; "text" (default) or "json")

Usage Examples:

"Delete bit.ly/ABC123 permanently"

bitly_get_link_destination - Look up where a short link points: its destination long URL plus basic metadata (works for any bitlink, including links you do not own)

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
response_format (optional; "text" (default) or "json")

Usage Examples:

"What URL does bit.ly/ABC123 point to?"

Analytics

Analytics are served by three tools, one per subject. Each takes a dimension that selects the report: a facet breakdown (e.g. countries, cities, devices) or over_time (a time series). The single-link and QR Code tools also offer summary (totals); group analytics instead offers top (best-performing links) and has no group-level summary — for an overall group count, total the over_time series.

bitly_get_link_analytics - Analytics for a single short link

over_time and summary report click counts; engagements and engagements_summary report the same time ranges with a clicks/scans/button-clicks breakdown.

Parameters:

bitlink_id (required; the short link in 'domain/hash' form, e.g. 'bit.ly/ABC123')
dimension (required; countries | cities | devices | referrers | referring_domains | over_time | summary | engagements | engagements_summary)
unit (optional; minute | hour | day | week | month)
units (optional; number of periods; default 30)
unit_reference (optional; ISO timestamp ending the range)
size (optional; number)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Which countries clicked bit.ly/ABC123 in the last 7 days?"

"Show me metrics over time for bit.ly/ABC123"

"How many total engagements has bit.ly/ABC123 received?"

bitly_get_group_analytics - Analytics across all links in a group (workspace)

Takes a dataset selecting what to measure. Valid dimensions depend on the dataset:

Dataset	Dimensions
agentic_traffic	summary
clicks	countries, cities, device_os, referrers, over_time, top
engagements	countries, cities, devices, referrers, referring_networks, over_time, top
qr_scans	countries, cities, over_time, top

devices is device form factor (mobile, desktop, ...); device_os is operating system (iOS, Android, Windows, ...).

agentic_traffic counts clicks from AI agents and assistants. It always returns a fixed 90-day total and ignores unit, units, and unit_reference.

Parameters:

group_guid (required)
dataset (required; agentic_traffic | clicks | engagements | qr_scans)
dimension (required; countries | cities | devices | device_os | referrers | referring_networks | over_time | summary | top; see matrix above)
unit (optional; minute | hour | day | week | month)
units (optional; number of periods; default 30)
unit_reference (optional; ISO timestamp ending the range)
size (optional; number)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Break down my group's QR scans by city"

"What are my top performing links this week?"

"How have my group's clicks trended over the last 30 days?"

"How much of my traffic came from AI agents?"

bitly_get_qr_code_analytics - Scan analytics for a single QR Code

Parameters:

qrcode_id (required)
dimension (required; countries | cities | device_os | browsers | over_time | summary)
unit (optional; minute | hour | day | week | month)
units (optional; number of periods; default 30)
unit_reference (optional; ISO timestamp ending the range)
size (optional; number)
response_format (optional; "text" (default) or "json")

Usage Examples:

"What operating systems scanned QR Code QR123456?"

"How many total scans does QR Code QR123456 have?"

QR Codes

bitly_create_qr_code - Create a new QR Code for a link

Parameters:

group_guid (required)
title (optional)
long_url (optional; destination to encode; required if bitlink_id not provided)
bitlink_id (optional; existing short link to encode; required if long_url not provided)
domain (optional)
archived (optional; boolean)
render_customizations (optional; object; foreground/background colors, gradients, frame, dot pattern)
expiration_at (optional; ISO 8601 "YYYY-MM-DDTHH:MM:SS+0000"; long_url-backed QR Codes only, on entitled accounts)
dynamic_routing (optional; object[]; up to 10 rules; decoupled (long_url-backed) QR Codes only)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Create a QR Code for bit.ly/ABC123 called 'Event Registration'"

"Create a QR Code for bit.ly/ABC123 titled 'Event Registration' in my marketing group"

"Create a QR Code for bit.ly/ABC123 with a blue foreground and white background"

bitly_get_qr_code - Get QR Code metadata

Parameters:

qrcode_id (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show details for QR Code QR123456"

bitly_get_qr_code_image - Return a QR Code's image as a base64 data URI (not a URL). Most agent UIs cannot render raw image data, so to view or download the image prefer the QR Code details page returned by bitly_get_qr_code and bitly_create_qr_code.

Parameters:

qrcode_id (required)
format (optional; svg | png; default "svg")
response_format (optional; "text" (default) or "json")

Usage Examples:

"Get the raw image data for QR Code QR123456 as a PNG"

bitly_update_qr_code - Update a QR Code's title, customizations, expiration, archived status, or dynamic routing rules

Parameters:

qrcode_id (required)
title (optional)
archived (optional; boolean)
render_customizations (optional; object; foreground/background colors, gradients, frame, dot pattern)
expiration_at (optional; ISO 8601 "YYYY-MM-DDTHH:MM:SS+0000"; pass "" to remove an existing expiration)
dynamic_routing (optional; object[]; up to 10 rules; decoupled (long_url-backed) QR Codes only)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Update QR Code QR123456 with title 'Updated Event QR' and archive it"

"Recolor QR Code QR123456 with a red foreground"

bitly_get_group_qr_codes - List QR Codes in a group with filtering and pagination

Parameters:

group_guid (required)
query (optional; search term)
archived (optional; on | off | both)
size (optional; results per page)
search_after (optional; pagination cursor from the previous response)
has_dynamic_routing (optional; on | off | both; filter to QR Codes with or without routing rules)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show QR Codes in group Bg123def456 that contain 'event'"

User & Organization

bitly_get_user - Get the authenticated user's profile

Parameters:

response_format (optional; "text" (default) or "json")

Usage Examples:

"Show my user profile"

bitly_get_organizations - List organizations the user can access

Parameters:

response_format (optional; "text" (default) or "json")

Usage Examples:

"List all organizations I can access"

bitly_get_groups - List groups (workspaces); optionally filter by organization

Parameters:

organization_guid (optional)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show all my groups"

bitly_get_group_details - Get a group's details, including its custom domains

Parameters:

group_guid (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Get details for group Bg123def456"

bitly_get_group_preferences - Get a group's preferences, including the default domain used when creating links for the group

Parameters:

group_guid (required)
response_format (optional; "text" (default) or "json")

Usage Examples:

"What is the default domain for group Bg123def456?"

"Show the preferences for my marketing group"

bitly_get_group_short_links - List links in a group with rich filtering

Parameters:

group_guid (required)
size (optional; results per page)
search_after (optional; pagination cursor from the previous response)
query (optional; search term)
tag (optional; string[]; links must carry every tag listed (AND))
created_before (optional; Unix timestamp)
created_after (optional; Unix timestamp)
archived (optional; on | off | both)
has_dynamic_routing (optional; on | off | both; filter to links with or without routing rules)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show links in group Bg123def456"

"Get the first 20 links in group Bg123def456 tagged 'campaign' created after 2024-01-01 (exclude archived)"

bitly_get_group_short_links_sorted - List group links sorted by performance

Parameters:

group_guid (required)
sort (required; clicks)
unit (optional; minute | hour | day | week | month)
units (optional; number of periods)
unit_reference (optional; ISO timestamp ending the range)
size (optional; number)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show top-performing links in group Bg123def456 by clicks over the last 30 days"

Custom Domains

bitly_get_custom_domains - List custom domains available to the user

Parameters:

response_format (optional; "text" (default) or "json")

Usage Examples:

"What custom domains can I use for shortening links?"

bitly_get_custom_link_details - Get custom link metadata and override history

Parameters:

custom_bitlink (required; a custom-keyword link, e.g. 'example.ly/spring-sale')
response_format (optional; "text" (default) or "json")

Usage Examples:

"Show details for example.ly/spring-sale"

Bulk Uploads

bitly_bulk_upload_validate - Validate a bulk upload request and obtain a signed URL for uploading a .CSV or .XLSX file

Parameters:

filename (required)
upload_type (required; "link", "qr_code", or "coupled_link")
group_guid (optional)
domain (optional)
template_id (optional; required for "qr_code" and "coupled_link"; "QTDTmplWLogo" or "QTDTmplNLogo")
response_format (optional; "text" (default) or "json")

Usage Examples:

"Bulk upload links.csv into group Bg123def456"

"Bulk create QR Codes from qr-batch.xlsx using the no-logo template"

bitly_bulk_upload_file - Upload a file to the signed URL returned by bitly_bulk_upload_validate

Parameters:

upload_url (required; signed URL from the validate step)
headers (required; object; headers from the validate step)
file_content (required)
content_type (optional)
response_format (optional; "text" (default) or "json")

Usage Examples:

"Upload the validated bulk file to complete the bulk request"

Data Export

bitly_export_data - Export link or QR data as a CSV, returned inline as a downloadable file

Parameters:

group_guid (required)
export_type (required; "link_engagements_timeseries", "link_engagements_batch", "links_list", or "qr_codes_list")
bitlinks (optional; string[]; fully qualified bitlinks; for the engagement exports)
unix_from_date (optional; "YYYY-MM-DD" UTC; required for "link_engagements_timeseries")
unix_to_date (optional; "YYYY-MM-DD" UTC)
include_metrics (optional; boolean; for "links_list" and "qr_codes_list" only)
filter (optional; object; required for "links_list" and "qr_codes_list")
response_format (optional; "text" (default) or "json")

Usage Examples:

"Export a CSV of all links in group Bg123def456"

"Export daily click totals for bit.ly/ABC123 over the last 30 days"