Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Bitly MCP connector

OAuth 2.1/DCR MarketingCRM & Sales

Connect with Bitly MCP for URL shortening, link analytics, and branded links.

Bitly MCP connector

  1. Install the SDK

    Section titled “Install the SDK”
    Terminal window
    npm install @scalekit-sdk/node

    Full SDK reference: Node.js | Python

  2. Set your credentials

    Section titled “Set your credentials”

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Authorize and make your first call

    Section titled “Authorize and make your first call”
    quickstart.ts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENV_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'bitlymcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Bitly MCP:', link)
    process.stdout.write('Press Enter after authorizing...')
    await new Promise(r => process.stdin.once('data', r))
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'bitlymcp_get_custom_domains',
      toolInput: {},
    })
    console.log(result)

What you can do

Section titled “What you can do”

Connect this agent connector to let your agent:

  • Create and manage short links — shorten URLs, create links with custom back-halves, update link metadata, and delete links
  • Create and manage QR codes — generate QR codes for links, update QR code settings, and retrieve QR code images
  • Analyze link performance — get click summaries, engagement metrics, and breakdowns by city, country, device, referrer, and referring domain
  • Analyze QR code scans — get scan summaries and breakdowns by city, country, device, and browser
  • Analyze group-level engagement — query top links, clicks, scans, and engagement trends across all links in a group
  • Manage account structure — retrieve organizations, groups, custom domains, and user details

Tool list

Section titled “Tool list”

Use the exact tool names from the Tool list below when you call execute_tool. If you’re not sure which name to use, list the tools available for the current user first.

bitlymcp_bulk_upload_file # Upload a CSV or XLSX file to the signed URL returned by bulk_upload_validate. Pass the upload_url, headers, and file_content from the validate response. Requires an enterprise plan. 6 params

Upload a CSV or XLSX file to the signed URL returned by bulk_upload_validate. Pass the upload_url, headers, and file_content from the validate response. Requires an enterprise plan.

Name Type Required Description
file_content string required The actual file content (CSV or XLSX file bytes as a string) from the conversation context.
headers object required The headers map returned from bulk_upload_validate (as a JSON object with string keys and string values).
upload_url string required The signed upload URL returned from bulk_upload_validate.
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
content_type string optional MIME type for the upload. e.g. text/csv for CSV files or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet for XLSX.
response_format string optional 'text' (default) or 'json'
bitlymcp_bulk_upload_validate # Validate a bulk upload request and get a signed upload URL. upload_type: 'link' (links only), 'qr_code' (QR codes, requires template_id), 'coupled_link' (both, requires template_id). Template IDs: 'QTDTmplWLogo' (with Bitly logo), 'QTDTmplNLogo' (without). Returns upload_url and headers for use with bulk_upload_file. Requires an enterprise plan. 7 params

Validate a bulk upload request and get a signed upload URL. upload_type: 'link' (links only), 'qr_code' (QR codes, requires template_id), 'coupled_link' (both, requires template_id). Template IDs: 'QTDTmplWLogo' (with Bitly logo), 'QTDTmplNLogo' (without). Returns upload_url and headers for use with bulk_upload_file. Requires an enterprise plan.

Name Type Required Description
filename string required Logical filename for the bulk upload (for example, "contacts.csv" or "links.xlsx").
upload_type string required Type of bulk upload. Must be exactly one of: "link", "qr_code", or "coupled_link".
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
domain string optional Optional short domain to use for created links. If omitted, backend defaults and validation apply.
group_guid string optional Optional group GUID to associate with this bulk upload. If omitted, the default group may be used.
response_format string optional 'text' (default) or 'json'
template_id string optional QR code template ID. Required for qr_code and coupled_link uploads. Use 'QTDTmplWLogo' to include Bitly logo, 'QTDTmplNLogo' to exclude it.
bitlymcp_create_qr_code # Create a QR code linked to a URL. Supports visual customizations (colors, patterns). Use create_short_link_with_qr to create both a short link and QR code in one step. 8 params

Create a QR code linked to a URL. Supports visual customizations (colors, patterns). Use create_short_link_with_qr to create both a short link and QR code in one step.

Name Type Required Description
group_guid string required The GUID of the group to create the QR code in
long_url string required The destination URL for the QR code
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
archived boolean optional Whether the QR code should be archived (default: false)
bitlink_id string optional Existing short link ID to use as destination
render_customizations object optional Visual customizations for the QR code as a JSON object. e.g. {"dot_pattern_color": "#EF8000", "dot_pattern_type": "rounded", "background_color": "#ffffff"}. Supports corner colors, gradient, and logo configuration.
response_format string optional 'text' (default) or 'json'
title string optional The title of the QR code
bitlymcp_expand # Look up the original long URL behind any Bitly short link. Returns destination URL and creation timestamp. 3 params

Look up the original long URL behind any Bitly short link. Returns destination URL and creation timestamp.

Name Type Required Description
bitlink_id string required The complete short link in 'domain/hash' format (e.g., 'bit.ly/ABC123' or 'custom-domain.com/keyword')
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
bitlymcp_get_custom_domains # List all custom domains (branded short domains) available to the user. These can be used instead of 'bit.ly' when creating links. 2 params

List all custom domains (branded short domains) available to the user. These can be used instead of 'bit.ly' when creating links.

Name Type Required Description
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
bitlymcp_get_group_details # Get metadata for a specific group by GUID, including name, organization, creation date, and BSDs. 3 params

Get metadata for a specific group by GUID, including name, organization, creation date, and BSDs.

Name Type Required Description
group_guid string required The unique identifier of the group (workspace)
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
bitlymcp_get_group_engagements_cities # Get engagement metrics (clicks + scans) for all links in a group, broken down by city. Requires a paid Bitly plan. 7 params

Get engagement metrics (clicks + scans) for all links in a group, broken down by city. Requires a paid Bitly plan.

Name Type Required Description
group_guid string required The unique identifier of the group (workspace)
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_group_engagements_countries # Get engagement metrics (clicks + scans) for all links in a group, broken down by country. Requires a paid Bitly plan. 7 params

Get engagement metrics (clicks + scans) for all links in a group, broken down by country. Requires a paid Bitly plan.

Name Type Required Description
group_guid string required The unique identifier of the group (workspace)
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_group_engagements_devices # Get engagement metrics (clicks + scans) for all links in a group, broken down by device type. Requires a paid Bitly plan. 7 params

Get engagement metrics (clicks + scans) for all links in a group, broken down by device type. Requires a paid Bitly plan.

Name Type Required Description
group_guid string required The unique identifier of the group (workspace)
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_group_engagements_over_time # Get engagement metrics (clicks + scans) for all links in a group as a time series. Requires a paid Bitly plan. 6 params

Get engagement metrics (clicks + scans) for all links in a group as a time series. Requires a paid Bitly plan.

Name Type Required Description
group_guid string required The unique identifier of the group (workspace)
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_group_engagements_referrers # Get engagement metrics for all links in a group broken down by referrer source (Facebook, Google, direct, etc.). Requires a paid Bitly plan. 7 params

Get engagement metrics for all links in a group broken down by referrer source (Facebook, Google, direct, etc.). Requires a paid Bitly plan.

Name Type Required Description
group_guid string required The unique identifier of the group (workspace)
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_group_engagements_referring_networks # Get engagement metrics for all links in a group broken down by referring network category. Requires a paid Bitly plan. 7 params

Get engagement metrics for all links in a group broken down by referring network category. Requires a paid Bitly plan.

Name Type Required Description
group_guid string required The unique identifier of the group (workspace)
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_group_engagements_top # Get top-performing links in a group ranked by total engagements. Requires a paid Bitly plan. 7 params

Get top-performing links in a group ranked by total engagements. Requires a paid Bitly plan.

Name Type Required Description
group_guid string required The unique identifier of the group (workspace)
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_group_qr_codes # List QR codes in a group with optional search and pagination. 7 params

List QR codes in a group with optional search and pagination.

Name Type Required Description
group_guid string required The unique identifier of the group (workspace)
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
archived string optional Filter by archived status: 'on' (archived only), 'off' (non-archived only), 'both' (all)
query string optional Search term to filter QR codes by title or destination URL
response_format string optional 'text' (default) or 'json'
search_after string optional Pagination cursor for retrieving next page of results
size string optional Number of QR codes to return (default: 50, max: 100)
bitlymcp_get_groups # List all groups (workspaces) the authenticated user has access to. Groups contain links and QR codes. Use the returned group_guid with other tools. 3 params

List all groups (workspaces) the authenticated user has access to. Groups contain links and QR codes. Use the returned group_guid with other tools.

Name Type Required Description
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
organization_guid string optional Optional organization GUID to filter groups by specific organization. If provided, only groups belonging to this organization will be returned.
response_format string optional 'text' (default) or 'json'
bitlymcp_get_organizations # List all organizations the authenticated user belongs to, including org GUIDs, names, tier, and associated custom domains. 2 params

List all organizations the authenticated user belongs to, including org GUIDs, names, tier, and associated custom domains.

Name Type Required Description
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
bitlymcp_get_qr_code # Get metadata for a QR code by qrcode_id: destination URL, type, customizations, and creation date. 3 params

Get metadata for a QR code by qrcode_id: destination URL, type, customizations, and creation date.

Name Type Required Description
qrcode_id string required The unique identifier of the QR code
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
bitlymcp_get_qr_code_image # Get the QR code image as a base64 data URI in SVG (default) or PNG format. Note: most AI UIs cannot render raw image data. 4 params

Get the QR code image as a base64 data URI in SVG (default) or PNG format. Note: most AI UIs cannot render raw image data.

Name Type Required Description
qrcode_id string required The unique identifier of the QR code
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
format string optional Image format: 'svg' or 'png' (default: svg)
response_format string optional 'text' (default) or 'json'
bitlymcp_get_qr_scan_metrics # Get QR scan metrics as a time series for a specific QR code. Requires a paid Bitly plan. 6 params

Get QR scan metrics as a time series for a specific QR code. Requires a paid Bitly plan.

Name Type Required Description
qrcode_id string required The unique identifier of the QR code
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_qr_scan_summary # Get total scan count for a specific QR code over a time range. Requires a paid Bitly plan. 6 params

Get total scan count for a specific QR code over a time range. Requires a paid Bitly plan.

Name Type Required Description
qrcode_id string required The unique identifier of the QR code
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_qr_scans_by_browser # Get QR scan metrics for a specific QR code broken down by browser. Requires a paid Bitly plan. 7 params

Get QR scan metrics for a specific QR code broken down by browser. Requires a paid Bitly plan.

Name Type Required Description
qrcode_id string required The unique identifier of the QR code
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_qr_scans_by_city # Get QR scan metrics for a specific QR code broken down by city. Requires a paid Bitly plan. 7 params

Get QR scan metrics for a specific QR code broken down by city. Requires a paid Bitly plan.

Name Type Required Description
qrcode_id string required The unique identifier of the QR code
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_qr_scans_by_country # Get QR scan metrics for a specific QR code broken down by country. Requires a paid Bitly plan. 7 params

Get QR scan metrics for a specific QR code broken down by country. Requires a paid Bitly plan.

Name Type Required Description
qrcode_id string required The unique identifier of the QR code
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_qr_scans_by_device # Get QR scan metrics for a specific QR code broken down by device OS. Requires a paid Bitly plan. 7 params

Get QR scan metrics for a specific QR code broken down by device OS. Requires a paid Bitly plan.

Name Type Required Description
qrcode_id string required The unique identifier of the QR code
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
size string optional Maximum number of results to return (default varies)
unit string optional Time granularity for metrics data: 'minute', 'hour', 'day', 'week', or 'month'. Determines how metrics are grouped by time. default: day
unit_reference string optional ISO 8601 end timestamp for the time range. The range covers the last 'units' periods ending on this date. e.g. 2024-01-31T00:00:00+0000
units string optional Number of time periods to include (e.g., '7' with unit='day' returns 7 days of data). Defaults to 30 when not specified.
bitlymcp_get_user # Get the authenticated user's profile including email addresses, 2FA status, and default group GUID. 2 params

Get the authenticated user's profile including email addresses, 2FA status, and default group GUID.

Name Type Required Description
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
response_format string optional 'text' (default) or 'json'
bitlymcp_update_qr_code # Update a QR code's title, visual customizations, or archived status. 6 params

Update a QR code's title, visual customizations, or archived status.

Name Type Required Description
qrcode_id string required The QR code ID to update
_meta object optional Optional metadata about this request. Include user_prompt, caller_agent (e.g. claude), intent_classification, conversation_id.
archived boolean optional Whether the QR code should be archived
render_customizations object optional Visual customizations for the QR code as a JSON object. e.g. {"dot_pattern_color": "#EF8000", "dot_pattern_type": "rounded", "background_color": "#ffffff"}. Supports corner colors, gradient, and logo configuration.
response_format string optional 'text' (default) or 'json'
title string optional The new title for the QR code