LinkMastery MCP Adapter for YOURLS

This package implements an MCP bridge, connecting the advanced reasoning capabilities of Claude Desktop with a personalized, self-managed YOURLS URL shortening infrastructure.

Developer: Martin Kessler

Primary Functionality Overview

YOURLS-MCP establishes a communication channel between Claude Desktop and your existing YOURLS deployment. Upon configuration, it empowers Claude to leverage your private URL shortening instance for all related tasks.

Core Capabilities

Initiate URL shortening via your dedicated YOURLS endpoint.
Define unique, memorable short links using specific keywords.
Aliasing Flexibility: Support for generating multiple distinct short identifiers pointing to the identical destination URL (a feature unique to this MCP implementation).
Access detailed metrics and accumulated statistics for shortened links.
Retrieve overall database performance metrics.
Intelligent handling of missing functionality via graceful degradation (fallbacks).
Full compatibility layer for extending features through YOURLS plugins.

Initial Setup Guide

Deployment Steps

# Obtain the source code
git clone https://github.com/kesslerio/yourls-mcp.git
cd yourls-mcp

# Resolve required node dependencies
npm install

Configuration within Claude Desktop

Modify your Claude Desktop configuration file to incorporate this server, pointing to the locally running adapter:

{
  "mcpServers": {
    "yourls": {
      "command": "node",
      "args": [
        "/full/path/to/yourls-mcp/yourls-mcp.js"
      ],
      "env": {
        "YOURLS_API_URL": "https://your-yourls-domain.com/yourls-api.php",
        "YOURLS_AUTH_METHOD": "signature", 
        "YOURLS_SIGNATURE_TOKEN": "your-secret-signature-token"
      }
    }
  }
}

Place this configuration file in the appropriate directory for your operating system: - macOS: ~/Library/Application Support/Claude/config.json - Windows: %APPDATA%\Claude\config.json - Linux: ~/.config/Claude/config.json

Functionality Deep Dive

Direct integration with Claude Desktop via the MCP framework.
Execute URL shortening requests immediately through Claude's interface.
Resolve contracted links back to their original targets.
Query click count reports for specific identifiers.
Support for user-defined short key assignment.
Secure communication utilizing signature-based verification.
Configuration managed entirely through environment parameters.

Customizable Parameters

These environment settings must be defined within the Claude Desktop configuration block:

Variable	Purpose	Default Value	Mandate
`YOURLS_API_URL`	The absolute path to the YOURLS API handler	-	Essential
`YOURLS_AUTH_METHOD`	Authentication strategy (`signature` or `password`)	`signature`	Optional
`YOURLS_SIGNATURE_TOKEN`	The secret credential for signature verification	-	Required for signature auth
`YOURLS_USERNAME`	Account identifier for password access	-	Required for password auth
`YOURLS_PASSWORD`	Security credential for password access	-	Required for password auth
`YOURLS_SIGNATURE_TTL`	Signature validity period in seconds	43200 (12 hours)	Optional

Exposed MCP Toolset

YOURLS-MCP exposes the following functional interfaces to Claude:

Primary Set

1. contract_long_url

Reduces a lengthy web address into a compact YOURLS link.

Arguments: - original_link (Mandatory): The full Uniform Resource Locator (URL) to be compressed. - custom_alias (Optional): A specific, user-chosen keyword for the short identifier. - link_label (Optional): Metadata title assigned to the shortened resource.

2. resolve_short_link

Determines the original, full destination URL from a contracted identifier.

Arguments: - identifier (Mandatory): The short URL or its associated keyword.

3. fetch_link_metrics

Retrieves performance data for a specific shortened URL.

Arguments: - identifier (Mandatory): The short URL or its associated keyword.

4. query_system_summary

Obtains aggregate operational statistics from the entire YOURLS installation.

Arguments: None

5. establish_unique_alias

Creates a specific short alias for a target URL, even overriding existing definitions or enforcing duplicates.

Arguments: - target_address (Mandatory): The destination URL. - alias_key (Mandatory): The desired unique keyword (e.g., "info" for yourdomain.com/info). - link_label (Optional): Descriptive title. - ignore_shortening_checks (Optional): Flag to bypass ShortShort plugin constraints (defaults to false). - force_duplicate_mode (Optional): If true, employs URL modification techniques to ensure multiple entries for the same target (defaults to false).

6. contract_with_utm_tracking

Shortens a URL while automatically embedding specified Google Analytics UTM parameters.

Arguments: - target_address (Mandatory): The URL requiring contraction. - traffic_source (Mandatory): UTM 'source' parameter (e.g., "linkedin"). - marketing_medium (Mandatory): UTM 'medium' parameter (e.g., "paid"). - campaign_tag (Mandatory): UTM 'campaign' identifier (e.g., "q4_promo"). - search_term (Optional): UTM 'term' parameter. - content_identifier (Optional): UTM 'content' parameter. - custom_alias (Optional): Custom keyword override. - link_label (Optional): Title for the link.

Plugin-Augmented Interfaces

7. retrieve_detailed_traffic_log

Fetches granular click activity reports for a short link within a specified temporal window. Prerequisite: YOURLS API ShortURL Analytics plugin must be active.

Arguments: - identifier (Mandatory): The short URL or keyword. - start_date (Mandatory): Initial date for reporting (Format: YYYY-MM-DD). - end_date (Optional): Final date for reporting (defaults to start date).

8. verify_url_existence

Checks if a given destination URL has already been mapped to a short link. Prerequisite: YOURLS API Contract plugin must be active.

Arguments: - target_address (Mandatory): The URL to check against the database.

9. reassign_target_address

Modifies an existing short link to redirect to a different ultimate destination. Prerequisite: YOURLS API Edit URL plugin must be active.

Arguments: - identifier (Mandatory): The short URL or keyword being modified. - new_destination (Mandatory): The URL it should redirect to now. - link_label (Optional): New title ("keep" or "auto").

10. rename_short_link_key

Changes the alias/keyword associated with an active short URL. Prerequisite: YOURLS API Edit URL plugin must be active.

Arguments: - old_alias (Mandatory): The current keyword. - new_alias (Mandatory): The replacement keyword. - target_url (Optional): The destination URL (defaults to current target). - link_label (Optional): New title ("keep" or "auto").

11. lookup_key_by_address

Finds all associated keywords pointing to a specific long URL. Prerequisite: YOURLS API Edit URL plugin must be active.

Arguments: - target_address (Mandatory): The full URL to search for. - require_exact_match (Optional): If false, returns all matches (default: true).

12. retire_short_link

Permanently removes a shortened link entry from the database. Prerequisite: YOURLS API Delete plugin must be active.

Arguments: - identifier (Mandatory): The short URL or keyword to be purged.

13. generate_link_manifest

Produces a comprehensive list of stored URLs, supporting advanced sorting, filtering, and paging. Prerequisite: YOURLS API List Extended plugin must be active.

Arguments: - sort_field (Optional): Field for ordering (keyword, url, clicks, etc.) (Default: timestamp). - order_direction (Optional): Sort orientation (ASC or DESC) (Default: DESC). - skip_count (Optional): Offset for pagination (Default: 0). - results_per_page (Optional): Limit on returned items (Default: 50). - search_criteria (Optional): Text to filter keywords against. - return_fields (Optional): Specific data points required (Default: all available fields).

14. fabricate_qr_code

Generates a scannable Quick Response (QR) graphical representation for a contracted link. Prerequisite: YOURLS-IQRCodes plugin must be installed.

Arguments: - identifier (Mandatory): The short URL or keyword. - image_scale (Optional): Pixel dimensions for the graphic. - frame_padding (Optional): Border thickness. - error_correction_level (Optional): Quality of redundancy (L, M, Q, or H). - output_type (Optional): Desired image file format (e.g., png, svg).

Exemplary Interaction Scenarios

Once the adapter is active, users can prompt Claude with directives such as:

Standard Operations Examples

"Shrink this destination: https://example.com/a-very-long-web-path-that-needs-trimming"
"Assign the keyword 'guide' to the address: https://example.com/instructions"
"I require the short link bysha.pe/resource to point to https://shapescale.com"
"Map the alias 'data' to point to our primary report URL."
"Can I register multiple aliases (guide1, guide2) for the same report URL?"
"Shorten this URL and include UTM tracking: source=email, medium=promo, campaign=holiday_deal"
"Resolve the target address for https://yourdomain.com/xyz"
"What is the current click volume for https://yourdomain.com/xyz?"
"Provide a global summary of all link interactions across the system."

Advanced Plugin Feature Prompts

"Detail the traffic breakdown for shortlink 'guide' throughout March 2025."
"What were the daily click counts for bysha.pe/resource between 2025-03-01 and 2025-03-31?"
"Has a short link been previously created for https://example.com/internal-page?"
"Redirect the short link 'guide' to the new location: https://example.com/updated-instructions"
"Please rename the short key 'guide' to 'documentation-v2'."
"What are all the keys currently mapped to https://example.com/internal-page?"
"Permanently erase the short link associated with the alias 'old-promo'."
"List the 20 most clicked links in descending order."
"Filter the URL list to show only those containing 'product' in the keyword."
"Generate a high-resolution QR code image for bysha.pe/resource."
"I need a standard size SVG QR code for the 'landing' alias."

Implementation Mechanics

YOURLS-MCP functions as an intermediary layer between Claude and YOURLS:

Claude Desktop initiates the adapter process on demand.
The adapter reads critical connection and security parameters from stored environment variables.
When Claude invokes a defined tool, the adapter executes the corresponding, correctly formatted API request against the YOURLS backend.
Results are packaged into a standardized response format and relayed back to Claude.

The Model Context Protocol (MCP) standard governs this communication, ensuring fluid, context-aware interaction with your URL management system.

Handling URL Duplication Uniquely

This adapter introduces functionality absent in vanilla YOURLS: creating numerous short identifiers for a single destination URL. Refer to Duplicate URL Handling Documentation for comprehensive details.

Two operational modes are available:

Plugin Implementation (Preferred): Relies on the supplementary Force Allow Duplicates plugin to achieve true singularity.
Address Modification Fallback: Injects time-based query parameters, making each entry technically distinct while maintaining functional redirection.

The system intelligently selects the appropriate method based on the configured YOURLS environment.

Plugin Interoperability and Degradation

YOURLS-MCP is engineered for maximum compatibility across standard and plugin-enhanced YOURLS installations, utilizing intelligent fallbacks when extensions are absent:

Supported Extensions & Fallback Logic

API ShortURL Analytics: Detailed temporal click data.
Degraded Mode: Offers only basic click counts via the core API if the analytics extension is missing.
API Contract: Pre-check for URL existence.
Degraded Mode: Queries the core statistics API using filtering parameters to simulate existence checks.
API Edit URL: For updating destinations or aliases.
Degraded Mode (Update): Attempts recreation using the identical keyword.
Degraded Mode (Keyword Change): Creates a new entry with the new keyword (the original remains active due to missing deletion capability).
Degraded Mode (Lookup): Employs filtering methods on the standard statistics API.
API Delete: Link removal capability.
Degraded Mode: Returns an informative message indicating that removal requires the specific plugin, as the base YOURLS API lacks a delete endpoint.
API List Extended: Advanced result set management.
Degraded Mode: Leverages the core API, performing sorting and pagination client-side.
YOURLS-IQRCodes: QR code generation.
Degraded Mode: No fallback available; operation fails without the plugin installed.
ShortShort: Manages the common error encountered when attempting to shrink an already contracted URL.
Compatibility: This error handling functions consistently whether the plugin is present or not.
Allow Existing URLs (External Plugin): Affects how YOURLS responds to duplicate submissions.
External Link: https://github.com/elder-oss/yourls-allow-existing-urls
Note: This plugin changes error codes but does not create unique secondary short links.
Our Strategy: The adapter implements the URL modification strategy to guarantee unique database records while preserving the user-facing experience.
Installation: Optional; our modification approach functions independently.
Force Allow Duplicates (Custom Plugin): The mechanism for achieving true, side-by-side duplicate short links.
Repository: https://github.com/kesslerio/yourls-force-allow-duplicates (Upcoming)
Purpose: Bypasses YOURLS' inherent single-key uniqueness constraint.
Activation: Set force=1 in API calls or use force_duplicate_mode=false with establish_unique_alias.
Installation Procedure:
1. Download package from repository.
2. Place folder in YOURLS/user/plugins/.
3. Activate via the YOURLS administration interface.

The Degraded Functionality Protocol

When a plugin-dependent function is requested but the corresponding plugin is inactive, YOURLS-MCP performs the following actions:

Automatically diagnoses the missing prerequisite.
Executes the closest available alternative operation when feasible.
Injects a fallback_activated: true flag into the resulting data structure.
Includes a fallback_constraints section detailing functional limitations.
For operations that cannot be approximated, it returns clear, actionable error messaging.

This design ensures operational continuity across diverse YOURLS setups while clearly communicating the benefits of a fully augmented installation.

Development and Validation

Integrated Validation Suites

The tests/integration/ folder houses various validation scripts:

Link Creation Tests:
test-custom-url.js: Validates the creation of aliased short links.
test-url-modification.js: Verifies the timestamp-based duplication fallback logic.
test-plugin-behavior.js: Assesses interaction with the Allow Existing URLs plugin.
Duplication Tests:
test-duplicate-urls.js: Confirms creation of multiple keys for one destination.
test-plugin-approach.js: Tests scenarios relying on the Force Allow Duplicates plugin.
Execution Command: bash # Execute a targeted test suite node tests/integration/test-custom-url.js

Auxiliary Scripts

Utility scripts are located in the scripts/ directory for routine maintenance:

create-random.js: Generates a randomly assigned short key for a specified address.
Other utilities for specialized link generation tasks.

Licensing

This project is distributed under the MIT License.

Project Context

YOURLS-MCP originated from Martin Kessler's need to unify YOURLS control with Claude Desktop and other Claude interfaces via the Model Context Protocol.

The supporting Force Allow Duplicates plugin was developed specifically to overcome the inherent limitation in YOURLS regarding multiple short keys mapping to one target address.

For support inquiries, bug reporting, or feature suggestions, please utilize the following channels: - YOURLS-MCP Issues: https://github.com/kesslerio/yourls-mcp/issues - Force Allow Duplicates Plugin Issues: https://github.com/kesslerio/yourls-force-allow-duplicates/issues (Upon repository activation)

link-mastery-mcp-adapter

Author

kesslerio

Quick Info

Actions

Tags