mcp-shlink
This server provides MCP tools to manage Shlink short URLs and tags.
Create shortened URLs with optional custom slug, tags, max visits, and expiration (valid_until).
List all shortened URLs with pagination info.
Get details of a specific short URL by short code, including metadata and visit count.
Delete shortened URLs by short code.
List all tags with their associated short URL counts.
Retrieve server metrics: per-tool call counts, error counts, and latency.
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., "@mcp-shlink Create a short URL for https://www.example.com with slug 'my-link'"
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.
mcp-shlink
A Model Context Protocol (MCP) server for Shlink link shortening service. This server exposes Shlink's URL shortening, management, and tagging capabilities as MCP tools for AI assistants.
Features
Create shortened URLs with custom slugs, tags, and expiration
List all shortened URLs with pagination info
Get details of specific URLs by short code
Delete shortened URLs
List and manage tags
Full type safety with Pydantic models
Built with the official MCP Python SDK
Related MCP server: DWZ Short URL MCP Server
Requirements
Python >= 3.10
A Shlink instance with API access
Installation
pip install mcp-shlinkConfiguration
Copy .env.example to .env (gitignored) or export the variables directly:
Variable | Description | Required |
| Your Shlink instance base URL (e.g., | Yes |
| Your Shlink API key | Yes |
| Environment name shown in logs (default: | No |
| Opt-in anonymous tool usage events (default: | No |
| Optional HTTP collector for usage events | No |
| Opt-in Sentry error tracking (see below) | No |
| Feature flags (see Features & flags) | No |
Generate an API key in Shlink:
shlink api-key:generate --name=my_api_keyFeatures & flags
Risky behavior ships behind environment-driven feature flags (default OFF):
Flag | Env override | Purpose |
|
| Retry Shlink 5xx/connection errors with exponential backoff |
|
| Stage deletions behind a confirmation step |
|
| Anonymous tool usage events |
Observability
Structured logging: one JSON line per event on stderr, including
trace_id,request_id,environment, and per-toolduration_ms. Credentials, tokens, and URLs are redacted automatically.Metrics: the built-in
get_metricstool reports per-tool call counts, error counts, and latency (mean/p95/max); metrics are also dumped at shutdown.Error tracking: set
SENTRY_DSNto enable Sentry (full stack traces with environment context). Install withpip install "mcp-shlink[error-tracking]".
Documentation
Architecture & service dependencies (generated diagram, verified in CI)
Runbooks (incident response)
Secrets management (policy and enforcement)
Usage
Running as a standalone MCP server
SHLINK_BASE_URL=https://shlink.example.com SHLINK_API_KEY=your-key python -m mcp_shlink.serverInstalling into Claude Desktop
uv run mcp install src/mcp_shlink/server.py --name "shlink"Running with MCP Inspector
SHLINK_BASE_URL=https://shlink.example.com SHLINK_API_KEY=your-key uv run mcp dev src/mcp_shlink/server.pyAvailable Tools
Tool | Description |
| Create a new shortened URL |
| List all shortened URLs |
| Get details of a URL by short code |
| Delete a shortened URL |
| List all tags |
| Server metrics: per-tool calls, errors, latencies |
Development
# Clone the repository
git clone https://github.com/magnus919/mcp-shlink
cd mcp-shlink
# Install in development mode
pip install -e ".[dev]"
# Install pre-commit hooks
pre-commit install
# Run tests (unit + integration, parallel, 80% coverage gate)
pytest
# Lint and format
ruff check .
ruff format .
# Type check
mypy src/
# Full verification
ruff check . && ruff format . --check && mypy src/ && pytestIntegration tests run against a local Shlink stub (tests/shlink_stub_server.py);
no real Shlink instance is needed.
Local interactive QA
You can exercise the full tool surface without a real Shlink deployment:
# 1. Start the local Shlink stub API
SHLINK_API_KEY=changeme python -m tests.shlink_stub_server --port 8765
# 2. Drive the MCP server with MCP Inspector against the stub
SHLINK_BASE_URL=http://127.0.0.1:8765 SHLINK_API_KEY=changeme \
uv run mcp dev src/mcp_shlink/server.pyInvoke any of the five tools in the Inspector UI; all are safe against the stub.
Project Structure
src/mcp_shlink/
├── server.py # FastMCP server entry point
├── client.py # Shlink API client
├── tools.py # MCP tool definitions
├── models.py # Pydantic models for API requests/responses
├── config.py # Typed settings loaded from environment
├── observability.py # Structured logs, redaction, trace ids, metrics
├── features.py # Feature flag registry
└── analytics.py # Opt-in anonymous usage events
tests/ # Unit + integration tests (local Shlink stub)
scripts/ # CI/pre-commit helper scripts
docs/ # Architecture, runbooks, secrets policyLicense
Apache 2.0. See LICENSE.
Available Tools
5 toolscreate_short_urlC
Create a new shortened URL in Shlink.
Inputs: long_url (required), tags, max_visits, custom_slug, +1 more. Returns: tags, long_url, short_url, short_code, +2 more
delete_short_urlC
Delete a shortened URL by its short code.
Inputs: short_code (required). Returns: result
get_short_urlA
Get details of a shortened URL by its short code.
Inputs: short_code (required). Returns: meta, tags, long_url, short_url, +3 more
list_short_urlsB
List all shortened URLs in Shlink.
Inputs: no named parameters. Returns: data, pagination
list_tagsA
List all tags in Shlink.
Inputs: no named parameters. Returns: data
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a distinct purpose: create, delete, get, list short URLs, and list tags. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (e.g., create_short_url, list_tags), with clear and predictable naming.
5 tools cover the core URL shortening domain reasonably well. The count is appropriate, though slightly on the lower end for a full-featured API.
Missing an update operation for short URLs, which is a notable gap. Basic CRUD would require update in addition to create, read, and delete.
Maintenance
Related MCP Connectors
Make, find, pause and track short links and QR codes from your AI assistant. Create short links with an optional custom address, title and tags; find links and QR codes; update, pause, resume, archive or restore them; and read click analytics (clicks, unique visitors, countries, referrers, devices, browsers) for a link, a QR code or the whole account. Sign in with OAuth and choose what the assistant may do. Every change can be undone; nothing is ever permanently deleted. Works on every plan, including Free.
Create and manage short links, track clicks, and automate URL management
Create short links and see their click counts from your AI assistant.
Make short links and QR codes and read click stats from your AI assistant.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to create, update, and manage short links through your Dub.co account, allowing for creation, modification, and deletion of custom shortened URLs.4MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to create, manage, and analyze short URLs through complete URL shortening functionality. Supports batch operations, custom domains, click statistics, and comprehensive link management.629 npm1MIT
- AlicenseAqualityCmaintenanceEnables to manage and analyze a Shlink URL-shortener instance with tools for short URLs, visits, tags, domains, redirect rules, QR codes, and Mercure integration.2312 npmMIT
- AlicenseAqualityBmaintenanceEnables users to shorten links, bulk create URLs, generate QR codes, manage and disable links, and retrieve click analytics from MCP clients like Claude, ChatGPT, Cursor, and n8n.9MIT