TinyURL MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@TinyURL MCP shorten https://example.com/pricing to the alias pricing-page"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 testThe 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.jsonThe 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 |
| Yes | Absolute path to the private token file. The file must be a regular, non-symlink file with mode |
| Yes | Absolute path to the private state directory. It must be a real, non-symlink directory with mode |
| No | API request timeout from |
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 |
|
|
No separate scope shown by TinyURL |
|
|
|
|
|
| Expiration fields in |
|
|
|
|
|
|
|
|
|
|
None required |
|
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 startTools
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.
Link management
Tool | Access | Purpose |
| 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. |
| Read-only | Reads one exact alias and returns its destination and available metadata. |
| Write | Updates metadata or renames one exact alias. It cannot change the destination. |
| Write | Changes the destination of one exact alias, redirecting existing traffic to the new URL. |
| Destructive write | Permanently deletes one exact alias. |
| Write | Toggles, archives, or unarchives one exact alias and verifies the resulting archive state. |
| Write | Sets or clears the expiration of one exact alias. |
Analytics
Tool | Access | Purpose |
| Read-only | Reads one fixed analytics report: |
| Read-only, sensitive | Reads a bounded page of raw analytics JSON over a date range. |
| Write | Enables or disables analytics collection for one exact alias. |
| Write, privacy-sensitive | Enables or disables public analytics sharing for one exact alias. |
Bulk operations
Tool | Access | Purpose |
| Bulk write | Submits 1-100 typed |
| Read-only | Reads the status of one bulk request. |
| Read-only | Reads a bounded page of one bulk request report. |
Server status
Tool | Access | Purpose |
| Read-only | Checks whether the configuration, token, and state directory appear usable. Does not call TinyURL or write state. |
Inputs
tinyurl_createrequiresurland accepts optionalaliasandexpires_at.expires_atis an ISO 8601 date-time or duration accepted by TinyURL, ornullfor no expiration.tinyurl_readrequiresalias.tinyurl_updaterequiresaliasand at least one ofnew_alias,new_stats,new_tags,new_expires_at, ornew_description.tinyurl_change_destinationrequiresaliasandurl.tinyurl_deleterequiresalias.tinyurl_archiverequiresaliasandaction(toggle,archive, orunarchive).togglealways performs one toggle;archiveandunarchiveread the current state first and skip a no-op write.tinyurl_set_expirationrequiresaliasandnew_expires_at(an ISO 8601 date-time/duration, ornullto clear the expiration).tinyurl_analytics_reportrequiresreportandfrom. Optional filters areto,alias,tag, anddomain.intervalis valid only fortimelineand acceptsminute,hour,day,week, ormonth.regionis valid only forlocationand acceptsworldor a two-letter country code.tinyurl_analytics_raw_logsrequiresfromand accepts optionalto,alias,tag,domain,offset(0-50000), andlimit(1-1000, default 100). The report returnstotal,returned,hasMore, andnextOffset.tinyurl_analytics_statusrequiresaliasand booleanenabled.tinyurl_analytics_sharingrequiresaliasand booleanpublic.tinyurl_bulk_createrequires between 1 and 100 items.createrequiresurl;updaterequiresaliasand at least onenew_*change;changerequiresaliasandurl;delete,archive, andunarchiverequirealias. Items may include up to 20 primitivemetadatavalues.tinyurl_bulk_statusrequires a positive integerbulkRequestId.tinyurl_bulk_reportrequires a positive integerbulkRequestIdand acceptsoffset(0-100000) andlimit(1-500, default 100).tinyurl_statustakes 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_deleteanddeleteitems insidetinyurl_bulk_createremove 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_createcall may contain up to 100 changes, includingchange,delete, andarchiveitems. Review the entire batch before submission.Destination changes redirect live traffic.
tinyurl_change_destinationandchangebulk 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
nullonly when the link should never expire.Analytics sharing can expose data.
tinyurl_analytics_sharingwithpublic: truemakes analytics publicly accessible. Review whether that is appropriate before changing it.Raw analytics logs are sensitive.
tinyurl_analytics_raw_logscan 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_unknownand 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
httporhttpsURLs.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 testThe 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 toolstinyurl_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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Create and manage TinyURL short links: aliases, destinations, tags, archive, click analytics.
Create and manage short links, track clicks, and automate URL management
Create, search and pause deep links; QR codes; analytics, taps, events; domains; webhooks.
Create branded short links and QR codes, and pull click analytics by country, device and referrer.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.629 npm1MIT
- AlicenseAqualityBmaintenanceEnables 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.2024 npm1MIT
- AlicenseAqualityBmaintenanceEnables 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.9MIT

esyURL MCP serverofficial
AlicenseNot gradedqualityCmaintenanceEnables 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