Skip to main content
Glama
TinyURL MCP

TinyURL MCP

by sklivvz

TinyURL MCP

A local stdio Model Context Protocol server for managing individual TinyURL aliases through the authenticated TinyURL API. It supports exact-alias link creation and changes, archive and expiration controls, analytics reports and settings, raw analytics logs, and bounded typed bulk operations.

It requires Node.js 20 or newer and has zero runtime dependencies. All calls use the fixed tinyurl.com domain and the fixed https://api.tinyurl.com API origin; callers cannot supply an arbitrary host, path, or endpoint.

Requirements

  • Node.js 20 or newer.

  • A TinyURL API token with the permissions needed for the tools you enable.

  • A private directory for the configuration, token, and server state.

Related MCP server: Linkly MCP Server

Setup

From a checkout, no dependency installation is required:

npm test

The tests use Node's built-in test runner and provider mocks; they do not need a TinyURL token.

1. Create private files

Use real absolute paths in place of the /path/to/... placeholders. The token file must be a regular file with mode 0600. The state directory and its immediate parent must be real directories with mode 0700.

mkdir -p /path/to/private/tinyurl-state
chmod 700 /path/to/private /path/to/private/tinyurl-state

printf '%s\n' '<your-tinyurl-api-token>' > /path/to/private/tinyurl-api-token
chmod 600 /path/to/private/tinyurl-api-token

cp config.example.json /path/to/private/tinyurl-config.json
chmod 600 /path/to/private/tinyurl-config.json
$EDITOR /path/to/private/tinyurl-config.json

The token file may contain a raw token or JSON using either token or apiToken:

{ "token": "<your-tinyurl-api-token>" }

2. Configure the server

config.example.json uses placeholders only:

{
  "tokenFile": "/path/to/private/tinyurl-api-token",
  "stateDir": "/path/to/private/tinyurl-state",
  "timeoutMs": 4000
}

Field

Required

Description

tokenFile

Yes

Absolute path to the private token file. The file must be a regular, non-symlink file with mode 0600.

stateDir

Yes

Absolute path to the private state directory. It must be a real, non-symlink directory with mode 0700; its immediate parent must also be 0700.

timeoutMs

No

API request timeout from 100 to 4000 milliseconds. Defaults to 4000.

The config file itself must be a regular, non-symlink file with mode 0600, no larger than 64 KiB, and its path must be absolute. Do not commit the config file, token file, or state directory.

3. Token permissions

TinyURL applies permissions to API tokens. The server uses one token, so grant the permissions required by the tools you expose. The tools declare these TinyURL token permissions:

TinyURL token permission

Tools

Create TinyURL

tinyurl_create

No separate scope shown by TinyURL

tinyurl_read

Update TinyURL

tinyurl_update

Change URL

tinyurl_change_destination

Manage TinyURL Expiration

Expiration fields in tinyurl_create, tinyurl_update and tinyurl_set_expiration

Delete TinyURL

tinyurl_delete

Archive TinyURL

tinyurl_archive

Use Analytics

tinyurl_analytics_report, tinyurl_analytics_status, tinyurl_analytics_sharing

Raw Analytics Logs

tinyurl_analytics_raw_logs

Use Bulk Requests

tinyurl_bulk_create, tinyurl_bulk_status, tinyurl_bulk_report

None required

tinyurl_status

tinyurl_status checks only whether the token file and state directory appear usable. It does not enumerate or validate token scopes. A token that lacks a required permission is rejected by TinyURL when the relevant tool runs, typically as an api_rejected error. Use least privilege and grant only the permissions needed by the tool set you intend to use.

4. Register with an MCP client

Set TINYURL_CONFIG_FILE to the absolute path of the private config file. Use Node.js 20 or newer to launch the server:

{
  "mcpServers": {
    "tinyurl": {
      "command": "node",
      "args": ["/path/to/tinyurl-mcp/main.mjs"],
      "env": {
        "TINYURL_CONFIG_FILE": "/path/to/private/tinyurl-config.json"
      }
    }
  }
}

The server communicates over stdin/stdout using MCP JSON-RPC. It is intended to be launched by an MCP client; running it directly starts a silent server that waits for protocol messages:

TINYURL_CONFIG_FILE=/path/to/private/tinyurl-config.json npm start

Tools

Every call is restricted to the fixed API origin. Link tools address one exact tinyurl.com alias; the optional domain field, where accepted, may only be tinyurl.com. Analytics reports are selected from a fixed set, and analytics date ranges, pages, and bulk IDs are validated.

Tool

Access

Purpose

tinyurl_create

Write

Creates one short link for an exact URL, with an optional alias and expiration. A verified prior result may be reused for the same exact operation.

tinyurl_read

Read-only

Reads one exact alias and returns its destination and available metadata.

tinyurl_update

Write

Updates metadata or renames one exact alias. It cannot change the destination.

tinyurl_change_destination

Write

Changes the destination of one exact alias, redirecting existing traffic to the new URL.

tinyurl_delete

Destructive write

Permanently deletes one exact alias.

tinyurl_archive

Write

Toggles, archives, or unarchives one exact alias and verifies the resulting archive state.

tinyurl_set_expiration

Write

Sets or clears the expiration of one exact alias.

Analytics

Tool

Access

Purpose

tinyurl_analytics_report

Read-only

Reads one fixed analytics report: timeline, general, weekday, hour, top_sources, top_languages, or location.

tinyurl_analytics_raw_logs

Read-only, sensitive

Reads a bounded page of raw analytics JSON over a date range.

tinyurl_analytics_status

Write

Enables or disables analytics collection for one exact alias.

tinyurl_analytics_sharing

Write, privacy-sensitive

Enables or disables public analytics sharing for one exact alias.

Bulk operations

Tool

Access

Purpose

tinyurl_bulk_create

Bulk write

Submits 1-100 typed create, update, change, delete, archive, or unarchive items. A batch can include destructive items.

tinyurl_bulk_status

Read-only

Reads the status of one bulk request.

tinyurl_bulk_report

Read-only

Reads a bounded page of one bulk request report.

Server status

Tool

Access

Purpose

tinyurl_status

Read-only

Checks whether the configuration, token, and state directory appear usable. Does not call TinyURL or write state.

Inputs

  • tinyurl_create requires url and accepts optional alias and expires_at. expires_at is an ISO 8601 date-time or duration accepted by TinyURL, or null for no expiration.

  • tinyurl_read requires alias.

  • tinyurl_update requires alias and at least one of new_alias, new_stats, new_tags, new_expires_at, or new_description.

  • tinyurl_change_destination requires alias and url.

  • tinyurl_delete requires alias.

  • tinyurl_archive requires alias and action (toggle, archive, or unarchive). toggle always performs one toggle; archive and unarchive read the current state first and skip a no-op write.

  • tinyurl_set_expiration requires alias and new_expires_at (an ISO 8601 date-time/duration, or null to clear the expiration).

  • tinyurl_analytics_report requires report and from. Optional filters are to, alias, tag, and domain. interval is valid only for timeline and accepts minute, hour, day, week, or month. region is valid only for location and accepts world or a two-letter country code.

  • tinyurl_analytics_raw_logs requires from and accepts optional to, alias, tag, domain, offset (0-50000), and limit (1-1000, default 100). The report returns total, returned, hasMore, and nextOffset.

  • tinyurl_analytics_status requires alias and boolean enabled.

  • tinyurl_analytics_sharing requires alias and boolean public.

  • tinyurl_bulk_create requires between 1 and 100 items. create requires url; update requires alias and at least one new_* change; change requires alias and url; delete, archive, and unarchive require alias. Items may include up to 20 primitive metadata values.

  • tinyurl_bulk_status requires a positive integer bulkRequestId.

  • tinyurl_bulk_report requires a positive integer bulkRequestId and accepts offset (0-100000) and limit (1-500, default 100).

  • tinyurl_status takes no arguments.

Examples

Placeholder values only. Replace them with the exact values you intend to use.

Create an alias with an optional expiration:

{
  "url": "https://example.com/page",
  "alias": "example-alias",
  "expires_at": "2030-01-01T00:00:00Z"
}

Read an alias:

{ "alias": "example-alias" }

Update metadata without changing the destination:

{
  "alias": "example-alias",
  "new_description": "Example description",
  "new_tags": ["example-tag"]
}

Change the destination of an existing alias:

{
  "alias": "example-alias",
  "url": "https://example.com/new-page"
}

Archive an alias:

{
  "alias": "example-alias",
  "action": "archive"
}

Set an expiration, or use null to clear it:

{
  "alias": "example-alias",
  "new_expires_at": "2030-01-01T00:00:00Z"
}

Read a timeline analytics report:

{
  "report": "timeline",
  "from": "2026-01-01",
  "to": "2026-01-31",
  "interval": "day",
  "alias": "example-alias"
}

Read a page of raw analytics logs:

{
  "from": "2026-01-01",
  "to": "2026-01-31",
  "alias": "example-alias",
  "offset": 0,
  "limit": 100
}

Enable analytics collection and disable public sharing:

{ "alias": "example-alias", "enabled": true }
{ "alias": "example-alias", "public": false }

Submit a bulk batch:

{
  "items": [
    {
      "operation": "create",
      "url": "https://example.com/one",
      "alias": "example-one"
    },
    {
      "operation": "archive",
      "alias": "example-two"
    }
  ]
}

Read bulk status and a report page:

{ "bulkRequestId": 12345 }
{ "bulkRequestId": 12345, "offset": 0, "limit": 100 }

Delete an alias permanently:

{ "alias": "example-alias" }

Safety

Writes affect live TinyURL state. There is no dry-run mode.

  • Confirm before every write. Check the exact alias, URLs, expiration value, analytics flags, and every bulk item before calling a write tool. MCP clients should ask the user for explicit confirmation, with extra scrutiny for deletion, destination changes, expiration changes, public analytics, and bulk batches.

  • Deletion is permanent. tinyurl_delete and delete items inside tinyurl_bulk_create remove short links and cannot be undone. Do not call them on production aliases without confirmation.

  • Bulk batches can combine destructive operations. A single tinyurl_bulk_create call may contain up to 100 changes, including change, delete, and archive items. Review the entire batch before submission.

  • Destination changes redirect live traffic. tinyurl_change_destination and change bulk items are security-sensitive. Verify the new URL before applying them.

  • Archive and expiration change link availability. Confirm the intended archive action and expiration. Use null only when the link should never expire.

  • Analytics sharing can expose data. tinyurl_analytics_sharing with public: true makes analytics publicly accessible. Review whether that is appropriate before changing it.

  • Raw analytics logs are sensitive. tinyurl_analytics_raw_logs can return IP addresses, referrers, devices, languages, countries, browser/OS data, and URLs. This is read-only data, but it should be handled as sensitive personal data and kept out of logs and source control.

  • Ambiguous writes are not retried automatically. On a timeout, network failure, server error, or unreadable provider response, a write may have been applied. The server reports write_outcome_unknown and leaves a private pending marker for the affected alias. Do not retry blindly or clear the state directory. Reconcile the exact alias first, then follow the reported next action.

  • Bulk ambiguity blocks further bulk submissions. A bulk submission is serialized and checkpointed before it is sent. If its outcome is unknown, a private bulk barrier blocks all later bulk submissions until an operator reconciles the batch. An exact repeat of a verified submission returns the stored bulkRequestId; do not submit a modified batch as a retry.

  • Preserve the state directory. It contains durable operation receipts, alias locks, bulk receipts, and mutation-outcome markers. Losing or editing it can make a retry unsafe.

  • Fixed access boundary. The server does not accept a caller-supplied host, path, API endpoint, or analytics endpoint. Reports are selected from a fixed set, aliases and bulk IDs are validated, and there is no anonymous fallback. Destinations must be absolute http or https URLs.

  • Protect the token and use least privilege. The token is read from the private token file and is sent only as a bearer credential to https://api.tinyurl.com. Grant only the scopes needed for the tools you expose, and keep the token out of environment variables, command lines, logs, and source control.

  • File modes are not a complete security boundary. Processes running as the same OS user may still access private files. Restrict host access, mount the configuration read-only where possible, or run the server under a separate identity.

Development

npm test

The implementation is plain ESM using Node.js built-in modules. There is no build step and no dependency installation step.

License

MIT © 2026 Marco Cecconi

Available Tools

15 tools
tinyurl_analytics_raw_logsA

Read bounded raw analytics JSON over GET /analytics/raw/json. from is required; to, alias, domain and tag are passed to the vendor. offset and limit bound the returned page and the report discloses total, returned, hasMore and nextOffset. Token permission: Analytics.

Inputs: from (required), to, tag, alias, +3 more.

tinyurl_analytics_reportB

Read one fixed TinyURL analytics report over GET /analytics/*. report selects timeline, general, weekday, hour, top_sources, top_languages or location. from is required; to, interval, alias, domain, tag and location region are validated and bounded. Token permission: Analytics.

Inputs: from (required), report (required), to, tag, +4 more.

tinyurl_analytics_sharingA

Enable or disable public analytics sharing for one exact TinyURL through PATCH /analytics/sharing. Requires alias and public. Uses the durable alias mutation barrier and invalidates create receipts. Token permission: Update TinyURL or Analytics settings.

Inputs: alias (required), public (required), domain.

tinyurl_analytics_statusA

Enable or disable analytics collection for one exact TinyURL through PATCH /analytics/status. Requires alias and enabled. Uses the durable alias mutation barrier and invalidates create receipts. Token permission: Update TinyURL or Analytics settings.

Inputs: alias (required), enabled (required), domain.

tinyurl_archiveA

Toggle, archive or unarchive one exact TinyURL through PATCH /archive. The vendor body is only domain+alias, so the endpoint toggles; this tool reads the current state first and toggles only when archive/unarchive requires a change. action=toggle always sends one toggle. Verifies the resulting archived boolean. Token permission: Archive TinyURL.

Inputs: alias (required), action (required), domain.

tinyurl_bulk_createA

Submit one bounded batch through POST /bulk (1-100 typed create/update/change/delete/archive/unarchive items). The request is serialized, checkpointed to a durable barrier before sending, and keyed by the canonical payload. A crash or unknown outcome blocks all further bulk submissions until an operator reconciles the batch; an exact repeat of a verified submission returns the stored bulkRequestId. Token permission: Bulk Requests.

Inputs: items (required), domain.

tinyurl_bulk_reportA

Read a bounded page of one bulk request report through GET /bulk/{bulkRequestId}/report. Requires a positive integer bulkRequestId; offset and limit bound the returned items and the response discloses total, returned, hasMore and nextOffset. Token permission: Bulk Requests.

Inputs: bulkRequestId (required), limit, offset.

tinyurl_bulk_statusA

Read one bulk request status through GET /bulk/{bulkRequestId}/status. Requires a positive integer bulkRequestId. Token permission: Bulk Requests.

Inputs: bulkRequestId (required).

tinyurl_change_destinationA

Change the destination of one exact TinyURL alias through PATCH /change. Requires alias and the exact new absolute http(s) url. Token permission: Update TinyURL.

Inputs: url (required), alias (required), domain.

tinyurl_createA

Create one exact TinyURL short link through POST /create. Requires url; domain is fixed to tinyurl.com; alias and expires_at are optional. Reuses durable operation results and never retries an ambiguous write blindly. Token permission: Create TinyURL.

Inputs: url (required), alias, domain, expires_at.

tinyurl_deleteB

Delete one exact TinyURL alias through DELETE /alias/{domain}/{alias}. Requires alias; domain is fixed to tinyurl.com. Token permission: Delete TinyURL.

Inputs: alias (required), domain.

tinyurl_readB

Read one exact TinyURL alias through GET /alias/{domain}/{alias}. Requires alias; domain is fixed to tinyurl.com. Token permission: Read TinyURL.

Inputs: alias (required), domain.

tinyurl_set_expirationB

Set or clear one exact TinyURL expiration through PATCH /update using new_expires_at, then verify the returned or re-read expiry. Requires alias and new_expires_at (string or null). Token permission: Update TinyURL.

Inputs: alias (required), new_expires_at (required), domain.

tinyurl_statusA

Read-only check for TinyURL connector configuration, token and private state directory. Does not create a link or write state.

Inputs: no named parameters.

tinyurl_updateA

Update metadata or rename one exact TinyURL alias through PATCH /update. Requires alias and at least one new_* field. Never changes the destination; use tinyurl_change_destination. Token permission: Update TinyURL.

Inputs: alias (required), domain, new_tags, new_alias, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 15 tools

    Disambiguation5/5

    Each tool has a clearly distinct target action: create/read/update/delete alias operations are separated, and update explicitly excludes destination and expiration changes. Analytics report vs raw logs vs status/sharing are distinct, and bulk create/status/report are cleanly scoped. No pair appears interchangeable.

    Naming Consistency5/5

    All tools use a consistent tinyurl_ prefix followed by snake_case action/resource names. The naming pattern is predictable throughout, including analytics and bulk subdomains.

    Tool Count5/5

    Fifteen tools fit the server's scope well: core alias lifecycle, analytics administration, bulk operations, and connector status. Each tool maps to a meaningful operation rather than redundant surface.

    Completeness5/5

    The tool surface covers TinyURL alias creation, reading, metadata updates, destination changes, deletion, archiving, expiration, analytics collection/sharing/reporting, and bulk operations with status/report retrieval. No obvious lifecycle or administrative gap is apparent for the stated purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to create, manage, and analyze short URLs through complete URL shortening functionality. Supports batch operations, custom domains, click statistics, and comprehensive link management.
      6
      29 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables interaction with Linkly's URL shortener and link management platform. Supports creating and managing short links, viewing analytics, configuring custom domains and webhooks, and exporting click data.
      20
      24 npm
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables users to shorten links, bulk create URLs, generate QR codes, manage and disable links, and retrieve click analytics from MCP clients like Claude, ChatGPT, Cursor, and n8n.
      9
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to create, update, organize, and delete short links; render styled QR codes; route visitors by device or country; and read click and scan statistics. Agents can also manage groups and custom domains while changing destinations without breaking printed QR codes or shared short URLs.
      MIT