shorten_urlLABSCO SUMMARY
Several short URLs for one destination.
That is the specific gap this fills: stock YOURLS refuses a second keyword for a URL it already has, so campaign links to the same page collide. Two approaches are offered and the server chooses based on whether the plugin is present, which is also why each plugin-backed tool names its dependency.
What it is
A Node MCP server that bridges Claude Desktop to your own YOURLS installation. It shortens and expands links, reads click statistics, and — unusually for YOURLS — creates several different short URLs for the same destination.
What you get
- Core —
shorten_url,expand_url,url_stats,db_stats,create_custom_url,shorten_with_analytics(adds UTM source, medium, campaign, term and content) - create_custom_url takes a keyword even when the destination is already in the database, with
bypass_shortshortandforce_url_modificationswitches for the awkward cases - Duplicate destinations handled two ways: the bundled Force Allow Duplicates plugin for true duplicates, or a timestamp-parameter fallback; the server picks based on your setup
- Plugin-backed tools, each stating the YOURLS plugin it needs:
url_analytics(date-range clicks),contract_url,update_url,change_keyword,get_url_keyword,delete_url,list_urls(sortable, paginated, filterable),generate_qr_code(size, border, error-correction level, format)
Requirements
Node and a clone of the repository — you point your client at yourls-mcp.js directly. YOURLS_API_URL is required. Authentication is either signature-based, which needs YOURLS_SIGNATURE_TOKEN, or password-based with YOURLS_USERNAME and YOURLS_PASSWORD; YOURLS_AUTH_METHOD defaults to signature and YOURLS_SIGNATURE_TTL to 43200 seconds. Seven of the tools depend on a YOURLS plugin being installed on your instance — the API ShortURL Analytics, API Contract, API Edit URL, API Delete, API List Extended and YOURLS-IQRCodes plugins.
Setup effort
Build from source — clone the repository, then follow the project's own run instructions
USE CASES
01
Shortening a campaign link with tracking
Pass the UTM source, medium and campaign and get the short URL back with them attached.
02
Giving the same page several campaign keywords
Create each custom keyword even though the destination is already shortened.
03
Checking how a link performed
Read total clicks, or the day-by-day breakdown across a date range.
04
Repointing or renaming an existing link
Change where a keyword points, or rename the keyword itself.
14 tools
Listed in project docs. Your client may show a different list.
expand_urlurl_statsdb_statscreate_custom_urlshorten_with_analyticsurl_analyticscontract_urlupdate_urlchange_keywordget_url_keyworddelete_urllist_urlsgenerate_qr_codeBEFORE YOU INSTALL
What to know first
Tools you get
14 tools named in the project's documentation.
Requires
- YOURLS_SIGNATURE_TOKEN in your environment
- YOURLS_PASSWORD in your environment
- YOURLS_USERNAME in your environment
Where it runs
The documented client runs the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
node yourls-mcp.jsMCP Clients
Claude Desktop
CLAUDE DESKTOP · JSON
{
"mcpServers": {
"yourls": {
"command": "node",
"args": [
"<YOUR_PATH_TO_YOURLS_MCP>/yourls-mcp.js"
],
"env": {
"YOURLS_API_URL": "<YOUR_LS_URL>/yourls-api.php",
"YOURLS_AUTH_METHOD": "signature",
"YOURLS_SIGNATURE_TOKEN": "<YOUR_SECRET_SIGNATURE_TOKEN>"
}
}
}
}The configuration on this page does not set YOURLS_PASSWORD and YOURLS_USERNAME; the project's instructions put them in a .env file. To supply them without depending on where the server looks for that file, use the block's "env" section.
