Skip to main content
Glama
XS Shlink MCP

XS Shlink MCP

by AlexGreenUK

XS Shlink MCP

npm version CI Node.js License: MIT

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

SHLINK_BASE_URL

Yes

-

Shlink origin without /rest, such as https://s.example.com

SHLINK_API_KEY

Yes

-

Shlink API key

SHLINK_API_VERSION

No

3

REST API major version

SHLINK_TIMEOUT_MS

No

10000

Per-request timeout in milliseconds

SHLINK_ALLOW_DESTRUCTIVE

No

false

Enables deletion tools when set to true

Never commit an API key. Tool results and errors do not include it.

Tools

Short URLs

  • list_short_urls

  • get_short_url

  • create_short_url

  • edit_short_url

  • delete_short_url

  • get_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_stats

  • get_short_url_visits

  • get_tag_visits

  • get_domain_visits

  • list_orphan_visits

  • list_non_orphan_visits

  • delete_short_url_visits

  • delete_orphan_visits

Redirect rules, tags, and domains

  • get_redirect_rules

  • set_redirect_rules

  • list_tags

  • rename_tag

  • delete_tags

  • list_domains

  • set_domain_redirects

Monitoring and integrations

  • shlink_health

  • get_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-mcp

macOS 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-mcp

Start 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 validate

The 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-run

Releases

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md. Use GitHub's private vulnerability reporting instead of opening a public issue for sensitive reports.

License

MIT

Available Tools

23 tools
create_short_urlC

Create a new Shlink short URL.

Inputs: longUrl (required), tags, title, domain, +7 more.

delete_orphan_visitsA
DestructiveIdempotent

Permanently erase all orphan visits. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.

Inputs: confirm (required).

delete_short_urlA
DestructiveIdempotent

Permanently delete a short URL. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.

Inputs: confirm (required), shortCode (required), domain.

delete_short_url_visitsA
DestructiveIdempotent

Permanently erase visit history for one short URL. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.

Inputs: confirm (required), shortCode (required), domain.

delete_tagsA
DestructiveIdempotent

Delete one or more tags. Requires SHLINK_ALLOW_DESTRUCTIVE=true and confirm=true.

Inputs: tags (required), confirm (required).

edit_short_urlC
Idempotent

Edit an existing Shlink short URL.

Inputs: shortCode (required), tags, title, domain, +7 more.

get_domain_visitsB
Read-onlyIdempotent

List visits for short URLs under a specific domain.

Inputs: domain (required), page, endDate, startDate, +2 more.

get_mercure_infoA
Read-onlyIdempotent

Get Shlink's Mercure real-time integration information when configured.

Inputs: no named parameters.

get_qr_code_urlA
Read-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_rulesB
Read-onlyIdempotent

List dynamic redirect rules configured for a short URL.

Inputs: shortCode (required), domain.

get_short_urlA
Read-onlyIdempotent

Get details for one Shlink short code.

Inputs: shortCode (required), domain.

get_short_url_visitsC
Read-onlyIdempotent

List visits for one short URL.

Inputs: shortCode (required), page, domain, endDate, +3 more.

get_tag_visitsA
Read-onlyIdempotent

List visits associated with short URLs carrying a specific tag.

Inputs: tag (required), page, endDate, startDate, +2 more.

get_visit_statsC
Read-onlyIdempotent

Get general visit statistics from Shlink.

Inputs: endDate, groupBy, startDate, excludeBots.

list_domainsA
Read-onlyIdempotent

List domains configured or used by Shlink.

Inputs: no named parameters.

list_non_orphan_visitsB
Read-onlyIdempotent

List visits that belong to valid short URLs.

Inputs: page, endDate, startDate, excludeBots, +1 more.

list_orphan_visitsB
Read-onlyIdempotent

List visits that did not resolve to a valid short URL.

Inputs: page, endDate, startDate, excludeBots, +1 more.

list_short_urlsA
Read-onlyIdempotent

List and search short URLs, with bounded pagination.

Inputs: page, tags, endDate, orderBy, +3 more.

list_tagsA
Read-onlyIdempotent

List Shlink tags, optionally including usage and visit statistics.

Inputs: withStats.

rename_tagA
Idempotent

Rename a tag everywhere it is used.

Inputs: newName (required), oldName (required).

set_domain_redirectsB
Idempotent

Configure optional fallback redirects for the base URL, invalid short URLs, and regular 404 paths.

Inputs: baseUrlRedirect, regular404Redirect, invalidShortUrlRedirect.

set_redirect_rulesA
Idempotent

Replace the dynamic redirect rules for a short URL. Rules are evaluated by Shlink in their provided order.

Inputs: shortCode (required), redirectRules (required), domain.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 23 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      F
      maintenance
      Enables AI assistants to interact with a Shlink URL shortening instance, allowing creation, listing, retrieval, and deletion of short URLs, as well as tag management.
      5
      4
      Apache 2.0
    • A
      license
      B
      quality
      C
      maintenance
      MCP 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.
      24
      46 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables creation and management of short links with custom slugs, QR repointing, and cookieless analytics from any MCP client.
      7 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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