shlink

MCP connector for a self-hosted Shlink server, tested against Shlink 5.1.8. It speaks REST API v3 over stdio and over stateless Streamable HTTP on localhost.

Shlink is MIT software. Copyright 2016-2024 Alejandro Celaya. This connector does not copy the PHP server. vendor/shlink-openapi is a copy of the Shlink OpenAPI spec, including that MIT license. The connector is not affiliated with Shlink.

shlink.routes.json lists every operation in that spec. 23 operations are tools. 3 are exclusions. scripts/gen-operations.mjs writes src/operations.ts from the spec. Do not edit src/operations.ts by hand.

SHLINK_URL and SHLINK_API_KEY are required. There is no default origin.

Setup

npm install
npm run ci
npm start
npm run start:http

npm start speaks stdio. npm run start:http serves Streamable HTTP at http://127.0.0.1:3000/mcp and GET /health. HTTP mode has no authentication of its own. Keep it on localhost.

{
  "mcpServers": {
    "shlink": {
      "command": "node",
      "args": ["/workspace/connectors/shlink/dist/index.js"],
      "env": {
        "SHLINK_URL": "http://127.0.0.1:8096",
        "SHLINK_API_KEY": "...",
        "SHLINK_ALLOW_WRITES": "false",
        "SHLINK_TOOLSETS": "short_urls,visits,tags,domains,redirect_rules,meta"
      }
    }
  }
}

Docker, HTTP, no authentication, keep it on localhost:

docker build -t shlink-mcp .
docker run -p 127.0.0.1:3000:3000 \
  -e SHLINK_URL=http://127.0.0.1:8096 \
  -e SHLINK_API_KEY=... \
  shlink-mcp

Do not put secrets in the image.

Regenerate the registry after a spec bump.

npm run gen:operations

scripts/live-check.mjs talks to a real server over stdio. It reads the API key from SHLINK_API_KEY or from SHLINK_API_KEY_FILE (default /workspace/tools/shlink/api.key). It unsets DATABASE_URL. It sets SHLINK_TOOLSETS=all for the child process. It prints pass or fail lines only, and it redacts the key.

Related MCP server: XS Shlink MCP

Config

Invalid values are reported by field name and issue code. The rejected value is not included.

The REST version path parameter is fixed at 3. Callers do not pass it. Health is GET /rest/health and sends no API key. Every other mapped route sends X-Api-Key.

Safety

Default toolsets are reads. Create, edit, delete, tag rename, tag delete, visit deletes, domain not-found redirects, and redirect-rule replacement live on separate toolsets. Those toolsets are off until SHLINK_TOOLSETS includes them or is all.

A write on an enabled toolset still needs confirm set to the boolean true and SHLINK_ALLOW_WRITES=true. The string "true" is rejected. Otherwise the tool returns a dry-run preview of method, path, query, and body, and it sends nothing.

Shlink errors use application/problem+json. HTTP 401 is unauthorized. HTTP 403 is forbidden. HTTP 404 is not found. HTTP 400, 409, and 422 are invalid input. HTTP 429 includes Retry-After when the header is present. Other failures are server, network, or timeout. Response bodies are capped at 1,000,000 bytes.

Tools

Default SHLINK_TOOLSETS publishes 6 tools and 14 read operations. SHLINK_TOOLSETS=all publishes 11 tools and 23 operations. Each tool takes action plus optional params, query, body, and, on write tools, confirm.

action help with optional target returns the fields for one action. Descriptions list action names only, so the tool list stays small.

params.shortCode is the path short code. params.tag and params.domain are path parameters on the visit routes that need them. Filters such as page, searchTerm, tags[], and domain go in query. Create and edit bodies follow the Shlink JSON schema. customSlug and tags are create fields.

What this connector leaves out

GET /rest/v{version}/short-urls/shorten is the deprecated query-string create. It accepts apiKey in the query string. Use create instead.

GET /{shortCode} is the public redirect. It records a visit and returns 302. It is not a JSON tool. Hit it with plain HTTP.

GET /{shortCode}/track is a tracking pixel. It returns an image.

Other Shlink MCP servers

gh search repos "shlink mcp" on 2026-11-03 returned three public repositories. A second search for mcp-shlink also returned magnus919/mcp-shlink. Stars below are from gh repo view the same day.

magnus919/mcp-shlink is archived Python, 4 stars, 6 tools (create_short_url, list_short_urls, get_short_url, delete_short_url, list_tags, get_metrics). Writes are not confirm-gated. list_short_urls takes no filters.

andrielson/shlink-mcp is TypeScript, 0 stars, 12 tools in src/tools.ts for short URLs, tags, and some visits. There is no confirm argument and no env kill switch. Domains, redirect rules, orphan visits, and health are absent.

AlexGreenUK/XS-Shlink-MCP is TypeScript, 0 stars, 23 tools, including QR, Mercure, domains, and redirect rules. Deletes need SHLINK_ALLOW_DESTRUCTIVE and confirm: true. Create, edit, rename, and redirect writes are not behind that flag.

bauer-group/IP-Shlink-MCPServer is Python, 0 stars, 23 tools generated from OpenAPI plus health and export_short_urls. It drops /short-urls/shorten, the public short URL, and Mercure. Inbound OAuth gates who may connect. Individual writes are not confirm-gated. One Shlink API key backs every caller.

This connector covers the same REST v3 resources as XS and Bauer, except QR and CSV export. It keeps reads on by default and keeps every write behind both an opt-in toolset and confirm plus SHLINK_ALLOW_WRITES=true.

Live check

See LIVE-CHECK.md for the last run against Shlink 5.1.8 at http://127.0.0.1:8096.

License

MIT. See LICENSE. The vendored OpenAPI spec stays under the Shlink MIT license in vendor/shlink-openapi/LICENSE.