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

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

• npm package
• GitHub releases
• Changelog

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