YOURLS Integration Service for Claude (MCP)

This document details the url-shortener-mcp-adapter, an implementation of the Model Control Protocol (MCP) designed to create a seamless connection between the Claude Desktop client and an existing, privately hosted YOURLS (Your Own URL Shortener) backend.

Developer: Martin Kessler

Conceptual Summary

This adapter functions as middleware, translating conversational commands from Claude into precise API interactions with your designated YOURLS installation. This permits users to manage their short links entirely through natural language input directed at Claude.

Primary Capabilities

• Condense lengthy Uniform Resource Locators (URLs) via the active YOURLS instance.
• Establish user-defined, memorable short links using specific keywords.
• Aliasing Flexibility: Allows the assignment of multiple distinct short links to a single target destination (a feature engineered beyond native YOURLS constraints).
• Access detailed metrics and click frequency reports for generated links.
• Query overall database performance metrics.
• Maintain intelligent operational resilience when interacting with optional YOURLS extensions.
• Offers comprehensive documentation and integrated testing utilities.

Initial Setup Procedure

Installation Prerequisite

bash

Obtain the project source code

git clone https://github.com/kesslerio/yourls-mcp.git cd yourls-mcp

Resolve software dependencies

npm install

Configuration for Claude Desktop

Modify your Claude Desktop configuration file (typically config.json in the application's support directory) to reference this adapter:

{ "mcpServers": { "yourls_bridge": { "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" } } } }

Configuration File Locations: - macOS: ~/Library/Application Support/Claude/config.json - Windows: %APPDATA%\Claude\config.json - Linux: ~/.config/Claude/config.json

Core Functionalities Exposed

This service exposes the following tools for use by the MCP client:

1. condense_uri

Shortens a supplied long URI.

Parameters: - url (Mandatory): The source URI requiring condensation. - keyword (Optional): A user-specified identifier for the resulting short link. - title (Optional): Descriptive label for the link.

2. resolve_uri

Recovers the original long URI from a provided short identifier.

Parameters: - shorturl (Mandatory): The short link or its associated keyword.

3. retrieve_link_metrics

Fetches performance statistics associated with a specific shortened URI.

Parameters: - shorturl (Mandatory): The short link or keyword.

4. fetch_database_summary

Retrieves high-level operational data from the entire YOURLS database.

Parameters: None

5. establish_custom_alias

Forces the creation of a unique short link using a specified keyword, even if that destination URL already has links defined.

Parameters: - url (Mandatory): The target destination URI. - keyword (Mandatory): The desired alias (e.g., "web" for bysha.pe/web). - title (Optional): Link title. - bypass_shortshort (Optional): Override for ShortShort plugin restrictions (default: false). - force_url_modification (Optional): Activates the timestamp-based uniqueness fallback (default: false).

6. generate_tagged_uri

Condenses a URI while automatically embedding Google Analytics UTM tracking parameters.

Parameters: - url (Mandatory): The URI to shorten. - source (Mandatory): UTM Source definition (e.g., "newsletter"). - medium (Mandatory): UTM Medium definition (e.g., "social"). - campaign (Mandatory): UTM Campaign definition (e.g., "q4_promo"). - term (Optional): UTM Term parameter. - content (Optional): UTM Content parameter. - keyword (Optional): Custom short link keyword. - title (Optional): Link title.

Extended Functionalities (Plugin Dependent)

Functions below require specific YOURLS plugins to be active for full performance.

7. query_detailed_traffic

Retrieves granular click analysis over a specified temporal range. Requires: API ShortURL Analytics plugin.

Parameters: - shorturl (Mandatory): Identifier. - date (Mandatory): Start date (YYYY-MM-DD). - date_end (Optional): End date (YYYY-MM-DD).

8. check_uri_existence

Verifies if a destination URI has already been mapped to any short link. Requires: API Contract plugin.

Parameters: - url (Mandatory): The destination URI to check.

9. overhaul_uri_target

Redirects an existing short link to a completely new destination URL. Requires: API Edit URL plugin.

Parameters: - shorturl (Mandatory): The alias to modify. - url (Mandatory): The new target location. - title (Optional): New title ("keep" or "auto").

10. rename_uri_alias

Modifies the keyword associated with a live short link. Requires: API Edit URL plugin.

Parameters: - oldshorturl (Mandatory): The current identifier. - newshorturl (Mandatory): The desired new identifier. - url (Optional): Target URL (defaults to original). - title (Optional): New title.

11. lookup_uri_by_target

Retrieves the short link keyword(s) mapped to a given long destination URL. Requires: API Edit URL plugin.

Parameters: - url (Mandatory): The long URI. - exactly_one (Optional): If false, retrieve all matches (default: true).

12. decommission_uri

Permanently removes a short link entry from the system. Requires: API Delete plugin.

Parameters: - shorturl (Mandatory): The alias to be removed.

13. inventory_uris

Generates a paginated, sortable, and filterable list of all managed short links. Requires: API List Extended plugin.

Parameters: - sortby (Optional): Attribute for ordering (e.g., clicks, timestamp). - sortorder (Optional): Sequence (ASC/DESC). - offset, perpage (Optional): Pagination controls. - query (Optional): Search string for filtering. - fields (Optional): Subset of data columns to return.

14. render_qr_graphic

Generates a machine-readable Quick Response code image for a short link. Requires: YOURLS-IQRCodes plugin.

Parameters: - shorturl (Mandatory): The identifier. - size, border, ecc, format (Optional): Image rendering parameters (pixel dimensions, error correction level, file type).

Operational Fallback Strategy & Plugin Dependency Details

YOURLS-MCP is engineered with graceful degradation in mind. When necessary plugins are absent, the adapter attempts to deliver partial or analogous functionality using core YOURLS APIs, marked clearly in the response payload (fallback_used: true).

Key Plugin Notes:

• Duplicate Handling: Unique support for multiple aliases per destination is achieved either via the custom yourls-force-allow-duplicates plugin (preferred) or, as a fallback, by appending non-interfering query parameters (e.g., timestamps) to ensure database uniqueness.
• Analytics Fallback: Detailed date-range analytics are simplified to basic click counts if the Analytics plugin is missing.
• Deletion/Updating: Operations requiring modification or deletion of existing records (e.g., decommission_uri, overhaul_uri_target) offer limited functionality or explicit error feedback without their respective enabling plugins.

Development Utilities

Developers can utilize scripts located in the tests/integration/ and scripts/ directories for unit validation and utility tasks (e.g., generating test data or running specific API sequence checks).

Licensing

This component is distributed under the MIT License.

Project Origin

Conceptualized and developed by Martin Kessler to enhance the interaction model between Claude systems and external URL management utilities via the MCP specification. The specialized plugin for duplicate URL creation addresses a fundamental limitation within standard YOURLS architecture.