Yourls MCP

YOURLS-MCP

用于将YOURLS URL缩短与Claude Desktop集成的模型控制协议（MCP）服务器。

作者 马丁·凯斯勒

概述

特性

• 使用YOURLS实例缩短URL
• 使用特定关键字创建自定义短网址
• 重复URL处理： 为同一目标URL创建多个短URL（YOURLS-MCP独有）
• 扩展的URL信息和统计数据
• 数据库统计
• 插件的智能回退
• 全面的文档和测试工具

快速开始

安装

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

# Install dependencies
npm install

配置

创建指向YOURLS-MCP安装的Claude Desktop配置文件：

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

将此文件保存到您的Claude Desktop配置目录，通常为：

• macOS： ~/Library/Application Support/Claude/config.json
• 窗户： %APPDATA%\Claude\config.json
• Linux： ~/.config/Claude/config.json

特性

• 通过MCP与Claude Desktop无缝集成
• 直接通过Claude缩短网址
• 展开缩短的URL以查看其目的地
• 检索链接的点击统计信息
• 自定义关键字支持
• 基于安全签名的身份验证
• 环境变量配置

配置选项

可以在Claude Desktop配置中设置以下环境变量：

可用的MCP工具

YOURLS-MCP为Claude提供了以下工具：

核心工具

1.短网址

使用YOURLS实例缩短长URL。

参数：

• url （必填）：要缩短的长URL
• keyword （可选）：短URL的自定义关键字
• title （可选）：URL的标题

2.expand_url

展开短URL以获取原始长URL。

参数：

• shorturl （必填）：要展开的短URL或关键字

3.url_starts

获取缩短URL的统计信息。

参数：

• shorturl （必填）：获取统计数据的短URL或关键字

4.数据统计

获取YOURLS实例的全局统计信息。

参数： 无

5.create_custom_url

使用特定关键字创建自定义短URL，即使对于数据库中已存在的URL也是如此。

参数：

• url （必填）：要缩短的目标URL
• keyword （必填）：短URL的自定义关键字（例如，bysha.pe/web的“web”）
• title （可选）：URL的标题
• bypass_shortshort （可选）：是否绕过阻止缩短已缩短网址的ShortShort插件（默认值：false）
• force_url_modification （可选）：是否强制使用URL修改方法为同一目的地创建多个短URL（默认值：false）

6.短路分析

使用Google Analytics UTM参数缩短长URL。

参数：

• url （必填）：要缩短的URL
• source （必填）：UTM源参数-标识流量来源（例如，“谷歌”、“时事通讯”、“推特”）
• medium （必填）：UTM媒介参数-标识营销媒介（例如，“cpc”、“social”、“email”）
• campaign （必填）：UTM活动参数-标识特定活动（例如，“summer_sale”、“product_launch”）
• term （可选）：UTM术语参数-标识付费搜索词
• content （可选）：UTM内容参数-区分指向同一URL的广告或链接
• keyword （可选）：短URL的自定义关键字
• title （可选）：URL的标题

基于插件的工具

7.url_analytics

获取日期范围内短URL的详细点击分析。 *需要安装API ShortURL分析插件。*

参数：

• shorturl （必填）：用于获取分析的短URL或关键字
• date （必填）：YYYY-MM-DD格式的分析开始日期
• date_end （可选）：YYYY-MM-DD格式的分析结束日期（如果未提供，则默认为开始日期）

8.合同\_ url

检查URL是否已被缩短，而未创建新的短URL。 *需要安装API合同插件。*

参数：

• url （必填）：检查是否被缩短的URL

9.更新url

更新现有的短URL以指向其他目标URL。 *需要安装API编辑URL插件。*

参数：

• shorturl （必填）：要更新的短URL或关键字
• url （必填）：新的目标URL
• title （可选）：可选的新标题（“keep”保持现有，“auto”从URL获取）

10.更改关键字

更改现有短URL的关键字。 *需要安装API编辑URL插件。*

参数：

• oldshorturl （必填）：现有的短URL或关键字
• newshorturl （必填）：要使用的新关键字
• url （可选）：可选URL（如果没有提供，将使用oldshorturl中的URL）
• title （可选）：可选的新标题（“keep”保持现有，“auto”从URL获取）

11.获取关键字

获取长URL的关键字。 *需要安装API编辑URL插件。*

参数：

• url （必填）：要查找的长URL
• exactly_one （可选）：如果为false，则返回此URL的所有关键字（默认值：true）

12.删除url

删除短URL。 *需要安装API删除插件。*

参数：

• shorturl （必填）：要删除的短URL或关键字

13.列表_世界

获取具有排序、分页和过滤选项的URL列表。 *需要安装API列表扩展插件。*

参数：

• sortby （可选）：要排序的字段（关键字、url、标题、ip、时间戳、点击）（默认值：时间戳）
• sortorder （可选）：排序顺序（ASC或DESC）（默认：DESC）
• offset （可选）：分页偏移量（默认值：0）
• perpage （可选）：每页结果数（默认值：50）
• query （可选）：按关键字筛选的可选搜索查询
• fields （可选）：要返回的字段（关键字、url、标题、时间戳、ip、点击）（默认：所有字段）

14.generate_qr_code

为缩短的URL生成二维码。 *需要安装YOURLS IQRCodes插件。*

参数：

• shorturl （必填）：生成二维码的短URL或关键字
• size （可选）：二维码大小（像素）
• border （可选）：二维码周围的边框宽度
• ecc （可选）：纠错级别：L（低）、M（中）、Q（四分位数）或H（高）
• format （可选）：图像格式（png、jpg、svg等）

使用示例

配置后，Claude将能够使用YOURLS工具，并显示以下提示：

核心功能示例

• “为我缩短此URL：https://example.com/very-long-url-that-needs-shortening"
• “使用关键字'docs'创建一个简短的URLhttps://example.com/documentation"
• “通过bysha.pe/web设置一个指向shapescale.com的自定义URL”
• “使用关键字'docs'为我们的文档创建自定义短URL”
• 为同一文档URL创建多个关键字（docs、docs2、docs3）
• “使用UTM跟踪参数为我们的活动创建一个简短的URL”
• “使用谷歌分析跟踪缩短此营销URL：来源=时事通讯，媒介=电子邮件，活动=summer_launch”
• “展开此短URL：https://yourdomain.com/abc"
• “我的短网址点击了多少次https://yourdomain.com/abc有？"
• “显示我的YOURLS实例的统计信息”

基于插件的功能示例

• “请为我提供2025年1月简写abc的详细分析”
• “显示bysha.pe/abc从2025-01-01到2025-01-31的点击统计数据”
• “上个月我的shortURL‘web’的每日流量是多少？”
• “检查此URL是否已被缩短：https://example.com/page"
• “是否有人已经为创建了一个简短的URLhttps://example.com/page?"
• “更新短URL'docs'的目标以指向https://example.com/new-documentation"
• “更改关键字'docs'指向的位置”
• 将短URL“docs”重命名为“documentation”
• “将我的短URL的关键字从'docs'更改为'documentation'”
• “这个长URL的关键字是什么：https://example.com/page?"
• “列出的所有短网址https://example.com/page"
• “删除短URL'docs'”
• “从我的YOURLS实例中删除关键字'docs'”
• “显示我的YOURLS数据库中最近的10个短网址”
• “列出所有按点击次数排序的短网址”
• “搜索包含“产品”的短URL”
• “为我的短网址‘docs’生成二维码”
• “为bysha.pe/web创建二维码”
• “给我一个带有高度纠错功能的产品页面二维码”
• “我需要一个更大的‘着陆’短网址二维码，使其达到300像素”
• “为我们的文档链接生成SVG二维码”

发展

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

# Install dependencies
npm install

# For local testing, create a claude-local-config.json file:
{
  "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"
      }
    }
  }
}

# Start the server directly (for testing)
node yourls-mcp.js

运作原理

YOURLS-MCP充当Claude Desktop和YOURLS实例之间的桥梁：

1. Claude Desktop在需要时启动YOURLS-MCP服务器
2. 服务器从环境变量中读取配置
3. 当Claude调用工具时，服务器会对YOURLS实例进行适当的API调用
4. 结果以结构化格式返回给Claude

服务器使用模型上下文协议（MCP）标准与Claude Desktop通信，允许与您的URL缩短器无缝集成和自然语言交互。

重复URL处理

YOURLS-MCP提供了一种独特的能力，可以为同一个目标URL创建多个短URL，这在YOURLS中是不受支持的。有关此功能的详细信息，请参阅 重复URL处理文档.

支持两种方法：

1. 插件方法 （推荐）：使用附带的Force Allow Duplicates插件创建真正的重复URL
2. URL修改方法 （回退）：添加时间戳参数，使每个URL在技术上唯一，同时保留功能

系统会根据您的YOURLS设置自动选择适当的方法。

与YOURLS插件的兼容性

YOURLS-MCP旨在与标准YOURLS安装和各种插件一起使用，在插件不可用时具有内置回退功能：

支持的具有回退功能的插件

YOURLS-MCP包括在未安装插件时扩展功能的智能回退：

• API ShortURL分析：有关日期范围的详细点击统计信息

- *回退行为*：当插件不可用时，通过核心YOURLS API提供基本点击统计

• API合同：在不创建URL的情况下检查URL是否存在

- *回退行为*：使用核心YOURLS统计API搜索具有筛选功能的现有URL

• API编辑URL：用于更新短网址和更改关键字

- *回退行为*: - 更新URL：尝试使用相同的关键字重新创建URL - 用于更改关键字：使用新关键字创建一个新的短URL（保留旧关键字，因为删除需要API Delete插件） - 获取URL关键字：使用核心YOURLS统计API进行过滤

• API删除：用于删除短网址

- *回退行为*：有限-提供删除需要插件的信息，因为核心YOURLS API不支持删除

• API列表扩展：用于具有排序和过滤功能的增强URL列表

- *回退行为*：使用核心YOURLS统计API进行客户端排序和分页

• YOURLS IQRCodes：用于从短网址生成二维码

- *回退行为*：无-需要安装插件

• ShortShort：在尝试缩短已缩短的URL时正确处理错误

- *兼容性*：无论是否安装插件，错误处理都有效

• 允许现有URL：修改YOURLS处理重复URL的方式

- *插件URL*: https://github.com/elder-oss/yourls-allow-existing-urls - *备注*：此插件将错误响应更改为成功响应，但实际上不会为现有目标URL创建新的短URL - *我们的解决方案*：YOURLS-MCP实现了一种URL修改方法，该方法添加了一个时间戳参数，使URL在数据库中唯一，同时保留了用户体验 - *安装*：可选-我们的URL修改方法可以在安装或不安装此插件的情况下使用

• 强制允许重复：真正允许为同一目标URL创建多个短URL

- *插件库*: https://github.com/kesslerio/yourls-force-allow-duplicates（即将推出） - *描述*：绕过YOURLS唯一URL约束的自定义插件 - *用法*：添加 force=1 到您的API请求或使用 force_url_modification=false 随着 create_custom_url 工具 - *安装*: 1. 从插件存储库下载 1. 复制 force-allow-duplicates 文件夹到您的 YOURLS/user/plugins/ 目录 1. 在YOURLS管理界面中激活插件

回退机制

当使用依赖插件的功能但未安装插件时，YOURLS-MCP：

1. 自动检测缺失的插件
2. 在可能的情况下提供适当的回退功能
3. 包括a fallback_used: true 回退激活时响应中的属性
4. 增加 fallback_limitations 回退功能降低时的信息
5. 对于完全不受支持的操作，返回信息性错误消息

这种方法确保YOURLS-MCP与尽可能多的YOURLS安装一起工作，同时仍然提供有关插件可用增强功能的清晰信息。

开发和测试

测试脚本

该项目包括各种测试脚本 tests/integration/ 目录：

• URL缩短测试:

- test-custom-url.js：使用特定关键字创建自定义URL的测试 - test-url-modification.js：测试处理重复URL的URL修改方法 - test-plugin-behavior.js：测试“允许现有URL”插件的行为

• 插件测试:

- test-duplicate-urls.js：使用不同关键字创建重复URL的测试 - test-plugin-approach.js：测试处理重复项的直接插件方法

• 运行测试:

  # Run a specific test
  node tests/integration/test-custom-url.js

实用程序脚本

这 scripts/ 目录包含用于常见操作的实用程序脚本：

• create-random.js：为指定目标创建随机短URL
• 用于特定URL创建任务的其他脚本

许可证

麻省理工学院

关于

YOURLS-MCP由Martin Kessler创建，旨在通过模型上下文协议（MCP）将YOURLS与Claude Desktop和其他Claude产品集成。

Force Allow Duplicates插件的开发是为了解决为同一目的地创建多个短网址的挑战，这在YOURLS中是不受支持的。

有关支持、问题或功能请求：

• YOURLS-MCP：https://github.com/kesslerio/yourls-mcp/issues
• 强制允许重复插件：https://github.com/kesslerio/yourls-force-allow-duplicates/issues（创建存储库后）