YOURLS

YOURLS-MCP creates a bridge between Claude Desktop and your self-hosted YOURLS URL shortener. When configured, it lets Claude automatically shorten URLs using your YOURLS installation and view detailed analytics and management options through MCP.

How to use

You interact with YOURLS-MCP through an MCP client such as Claude Desktop. After you set up the local MCP server, Claude can shorten URLs, expand them to their destination, and fetch statistics. You can also perform advanced operations such as creating custom short URLs with specific keywords, generating QR codes, or attaching analytics parameters to shortened URLs. If you have the right plugins installed, you can access extended features like detailed click analytics and URL management actions. The server automatically handles fallbacks when plugins are unavailable and returns clear information about any limitations.

How to install

Prerequisites: you need Node.js installed on your system. You also need a self-hosted YOURLS instance accessible via its API.

Install YOURLS-MCP locally by cloning the project, then installing dependencies.

# Clone the repository
git clone https://github.com/kesslerio/yourls-mcp.git
cd yourls-mcp

# Install dependencies
npm install

Configuration and running the MCP server

Configure the MCP server in your Claude Desktop setup to point at the local YOURLS-MCP instance. Use the following configuration as a starting point. It runs the MCP server locally via Node.js and passes the required environment variables for YOURLS authentication and API access.

{
  "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"
      }
    }
  }
}

"],"language":"code"}]},{

## Additional configuration notes

The MCP server reads configuration from environment variables. Use the variables shown above to point to your YOURLS API, choose an authentication method, and provide the corresponding secret or credentials. You can also supply a time-to-live for signatures with YOURLS\_SIGNATURE\_TTL if you want shorter or longer-lived signatures.

## Tools and capabilities shown in this guide

Core interactions you can perform through YOURLS-MCP include shortening URLs, expanding short URLs, and retrieving statistics. You can also create custom short URLs with a specific keyword, shorten with analytics tracking, and generate QR codes for short URLs. If you enable plugin-based features in YOURLS, you gain access to extended analytics and URL management operations.

## Security considerations

Use secure, signed authentication when possible and restrict the YOURLS\_API\_URL to trusted networks. Keep your YOURLS\_SIGNATURE\_TOKEN and any passwords or API keys in a secure secret store or environment manager. Review plugin requirements and enable fallbacks so that you have a predictable behavior if a plugin is unavailable.

## Troubleshooting tips

If Claude cannot access your YOURLS instance or returns errors, verify that the YOURLS\_API\_URL is correct and reachable from the host running YOURLS-MCP. Ensure that YOURLS\_AUTH\_METHOD is set to a method you have configured, and that credentials or tokens are valid. Check that the MCP server process is running (node yourls-mcp.js) and that the environment variables are correctly loaded.

## Notes on plugins and fallbacks

YOURLS-MCP supports plugin-based enhancements but provides intelligent fallbacks if plugins are missing. This means you can still shorten URLs, view basic statistics, and perform core tasks even if you do not have all YOURLS plugins installed. The system marks responses with fallback indicators when a feature relies on a missing plugin.

## Available tools

### shorten\_url

Shortens a long URL using your YOURLS instance. Parameters: url (required), keyword (optional), title (optional)

### expand\_url

Expands a short URL to the original long URL. Parameters: shorturl (required)

### url\_stats

Gets statistics for a shortened URL. Parameters: shorturl (required)

### db\_stats

Gets global statistics for your YOURLS instance. Parameters: None

### create\_custom\_url

Creates a custom short URL with a specific keyword, even if the URL already exists. Parameters: url (required), keyword (required), title (optional), bypass\_shortshort (optional), force\_url\_modification (optional)

### shorten\_with\_analytics

Shortens a URL with Google Analytics UTM parameters. Parameters: url, source, medium, campaign, term (optional), content (optional), keyword (optional), title (optional)

### url\_analytics

Gets detailed click analytics for a short URL within a date range. Requires API ShortURL Analytics plugin. Parameters: shorturl, date, date\_end (optional)

### contract\_url

Check if a URL has already been shortened without creating a new short URL. Requires API Contract plugin. Parameters: url

### update\_url

Update an existing short URL to point to a new destination. Requires API Edit URL plugin. Parameters: shorturl, url, title (optional)

### change\_keyword

Change the keyword of an existing short URL. Requires API Edit URL plugin. Parameters: oldshorturl, newshorturl, url (optional), title (optional)

### get\_url\_keyword

Get the keyword(s) for a long URL. Requires API Edit URL plugin. Parameters: url, exactly\_one (optional)

### delete\_url

Delete a short URL. Requires API Delete plugin. Parameters: shorturl

### list\_urls

List URLs with sorting and pagination. Requires API List Extended plugin. Parameters: sortby, sortorder, offset, perpage, query, fields

### generate\_qr\_code

Generate a QR code for a shortened URL. Requires YOURLS-IQRCodes plugin. Parameters: shorturl, size, border, ecc, format