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: Linkly MCP Server

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

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