YOURLS MCP Server

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.

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