XS Shlink 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., "@XS Shlink MCP list my short URLs"
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.
XS Shlink MCP
A local Model Context Protocol server for managing and analyzing a Shlink URL-shortener instance.
XS Shlink MCP runs over stdio, keeps the Shlink API key on the machine running
the MCP client, and does not require Docker or a separate hosted service.
Features
23 tools for short URLs, visits, tags, domains, redirect rules, QR codes, and Mercure integration information
Typed and validated tool inputs
Structured Shlink API errors with request IDs
Bounded pagination and request timeouts
Destructive operations disabled by default
Windows, macOS, and Linux support through Node.js
Related MCP server: opn-mcp
Requirements
Node.js 20 or newer
A reachable Shlink instance
A Shlink API key
The initial release was tested with Shlink 5.1.5 and REST API version 3.
Quick start
Configure an MCP client to launch the published npm package:
{
"mcpServers": {
"shlink": {
"command": "npx",
"args": ["-y", "xs-shlink-mcp"],
"env": {
"SHLINK_BASE_URL": "https://s.example.com",
"SHLINK_API_KEY": "replace-me",
"SHLINK_API_VERSION": "3",
"SHLINK_ALLOW_DESTRUCTIVE": "false"
}
}
}
}On Windows, use "command": "npx.cmd" if the MCP client does not resolve the
.cmd shim automatically.
The MCP client starts and stops the server automatically. Do not run ordinary
interactive commands through the server's standard input because stdio is
reserved for MCP protocol messages.
Configuration
Variable | Required | Default | Description |
| Yes | - | Shlink origin without |
| Yes | - | Shlink API key |
| No |
| REST API major version |
| No |
| Per-request timeout in milliseconds |
| No |
| Enables deletion tools when set to |
Never commit an API key. Tool results and errors do not include it.
Tools
Short URLs
list_short_urlsget_short_urlcreate_short_urledit_short_urldelete_short_urlget_qr_code_url
get_qr_code_url supports Shlink's QR-code customization parameters: size,
margin, PNG or SVG format, error-correction level, block-size rounding, and
foreground/background colors. Shlink deprecated its built-in QR-code endpoint
in version 4.5, so this tool is provided for compatibility with instances that
still expose it.
Analytics and visits
get_visit_statsget_short_url_visitsget_tag_visitsget_domain_visitslist_orphan_visitslist_non_orphan_visitsdelete_short_url_visitsdelete_orphan_visits
Redirect rules, tags, and domains
get_redirect_rulesset_redirect_ruleslist_tagsrename_tagdelete_tagslist_domainsset_domain_redirects
Monitoring and integrations
shlink_healthget_mercure_info
All deletion tools require both SHLINK_ALLOW_DESTRUCTIVE=true and an explicit
confirm: true tool argument.
Test with MCP Inspector
Set the API key in the current shell, then launch the published package.
PowerShell:
$env:SHLINK_API_KEY="replace-me"
npx.cmd -y @modelcontextprotocol/inspector -e "SHLINK_BASE_URL=https://s.example.com" -e "SHLINK_API_KEY=$env:SHLINK_API_KEY" -e "SHLINK_API_VERSION=3" -e "SHLINK_ALLOW_DESTRUCTIVE=false" -- npx.cmd -y xs-shlink-mcpmacOS or Linux:
export SHLINK_API_KEY="replace-me"
npx -y @modelcontextprotocol/inspector \
-e SHLINK_BASE_URL=https://s.example.com \
-e SHLINK_API_KEY="$SHLINK_API_KEY" \
-e SHLINK_API_VERSION=3 \
-e SHLINK_ALLOW_DESTRUCTIVE=false \
-- npx -y xs-shlink-mcpStart with shlink_health, followed by list_short_urls.
Local development
git clone https://github.com/AlexGreenUK/XS-Shlink-MCP.git
cd XS-Shlink-MCP
npm install
npm run validateThe automated tests use mocked Shlink responses. They do not require or modify a live Shlink instance.
Useful commands:
npm run dev
npm run build
npm test
npm pack --dry-runReleases
Contributing
See CONTRIBUTING.md.
Security
See SECURITY.md. Use GitHub's private vulnerability reporting instead of opening a public issue for sensitive reports.
License
Available Tools
23 toolscreate_short_urlC
Create a new Shlink short URL.
Inputs: longUrl (required), tags, title, domain, +7 more.
delete_orphan_visitsADestructiveIdempotent
Permanently erase all orphan visits. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.
Inputs: confirm (required).
delete_short_urlADestructiveIdempotent
Permanently delete a short URL. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.
Inputs: confirm (required), shortCode (required), domain.
delete_short_url_visitsADestructiveIdempotent
Permanently erase visit history for one short URL. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.
Inputs: confirm (required), shortCode (required), domain.
delete_tagsADestructiveIdempotent
Delete one or more tags. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.
Inputs: tags (required), confirm (required).
edit_short_urlCIdempotent
Edit an existing Shlink short URL.
Inputs: shortCode (required), tags, title, domain, +7 more.
get_domain_visitsBRead-onlyIdempotent
List visits for short URLs under a specific domain.
Inputs: domain (required), page, endDate, startDate, +2 more.
get_mercure_infoARead-onlyIdempotent
Get Shlink's Mercure real-time integration information when configured.
Inputs: no named parameters.
get_qr_code_urlARead-onlyIdempotent
Build the public Shlink QR-code image URL for a short code. This returns a URL rather than downloading binary image data.
Inputs: shortCode (required), size, color, domain, +5 more.
get_redirect_rulesBRead-onlyIdempotent
List dynamic redirect rules configured for a short URL.
Inputs: shortCode (required), domain.
get_short_urlARead-onlyIdempotent
Get details for one Shlink short code.
Inputs: shortCode (required), domain.
get_short_url_visitsCRead-onlyIdempotent
List visits for one short URL.
Inputs: shortCode (required), page, domain, endDate, +3 more.
get_tag_visitsARead-onlyIdempotent
List visits associated with short URLs carrying a specific tag.
Inputs: tag (required), page, endDate, startDate, +2 more.
get_visit_statsCRead-onlyIdempotent
Get general visit statistics from Shlink.
Inputs: endDate, groupBy, startDate, excludeBots.
list_domainsARead-onlyIdempotent
List domains configured or used by Shlink.
Inputs: no named parameters.
list_non_orphan_visitsBRead-onlyIdempotent
List visits that belong to valid short URLs.
Inputs: page, endDate, startDate, excludeBots, +1 more.
list_orphan_visitsBRead-onlyIdempotent
List visits that did not resolve to a valid short URL.
Inputs: page, endDate, startDate, excludeBots, +1 more.
list_short_urlsARead-onlyIdempotent
List and search short URLs, with bounded pagination.
Inputs: page, tags, endDate, orderBy, +3 more.
list_tagsARead-onlyIdempotent
List Shlink tags, optionally including usage and visit statistics.
Inputs: withStats.
rename_tagAIdempotent
Rename a tag everywhere it is used.
Inputs: newName (required), oldName (required).
set_domain_redirectsBIdempotent
Configure optional fallback redirects for the base URL, invalid short URLs, and regular 404 paths.
Inputs: baseUrlRedirect, regular404Redirect, invalidShortUrlRedirect.
set_redirect_rulesAIdempotent
Replace the dynamic redirect rules for a short URL. Rules are evaluated by Shlink in their provided order.
Inputs: shortCode (required), redirectRules (required), domain.
shlink_healthARead-onlyIdempotent
Check whether the configured Shlink instance is healthy.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Every tool targets a distinct resource and action. CRUD operations for short URLs are separated from visit management, tags, domains, and redirect rules. Even similar-sounding tools like get_visit_stats and get_short_url_visits are clearly scoped to global vs per-URL statistics.
The majority of tools follow a clean verb_noun pattern (list_short_urls, create_short_url, delete_tags). The only outlier is shlink_health, which uses a prefix instead of a verb-based name, creating a minor inconsistency.
With 23 tools, this server sits in the 'heavy' range (16-25). While the breadth of Shlink's features justifies many tools, the count is above the typical well-scoped range and may feel overwhelming for basic use cases.
The tool surface covers the full lifecycle of URL shortening: CRUD for short URLs, visit retrieval and deletion (including orphan/non-orphan), tag management, domain configuration, redirect rules, QR code generation, and health checks. No obvious gaps in core functionality.
Maintenance
Related MCP Connectors
Create and manage short links and QR codes, and read click analytics, on your own domain.
Short links, QR codes, link and website analytics: create and edit links, read clicks and visitors.
Create and manage short links, track clicks, and automate URL management
Related MCP Servers
- AlicenseBqualityFmaintenanceEnables AI assistants to interact with a Shlink URL shortening instance, allowing creation, listing, retrieval, and deletion of short URLs, as well as tag management.54Apache 2.0
- AlicenseBqualityCmaintenanceMCP server for opn.onl, the open-source self-hostable URL shortener. Shorten links, read click analytics, generate branded QR codes, and manage links — against the hosted service or your own instance.2446 npm2MIT
- AlicenseNot gradedqualityCmaintenanceEnables creation and management of short links with custom slugs, QR repointing, and cookieless analytics from any MCP client.7 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables shortening URLs, expanding short links, and retrieving link and database statistics from a self-hosted link-shortener via its HTTP API, with confirm-gated writes and caching.MIT