YOURLS-MCP

YOURLS-MCP

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

**作者：**马丁·凯斯勒

概述

YOURLS-MCP 在Claude 桌面和您自托管的YOURLS网址缩短服务实例之间搭建了一座桥梁。配置完成后，Claude 可以使用您个人的 YOURLS 安装自动缩短网址。

特征

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

快速入门

安装

配置

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

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

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

特征

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

配置选项

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

可用的 MCP 工具

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

核心工具

1. 缩短网址

使用您的 YOURLS 实例缩短长 URL。

参数：

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

2. expand_url

将短 URL 扩展为原始长 URL。

参数：

• shorturl （必填）：需要扩展的短网址或关键字

3. url_stats

获取缩短的 URL 的统计信息。

参数：

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

4. db_stats

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

**参数：**无

5. 创建自定义 URL

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

参数：

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

6. 使用分析缩短

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

参数：

• url （必填）：需要缩短的 URL
• source （必需）：UTM 源参数 - 标识流量来源（例如“google”、“newsletter”、“twitter”）
• medium （必需）：UTM 媒介参数 - 标识营销媒介（例如“cpc”、“社交”、“电子邮件”）
• campaign （必需）：UTM 活动参数 - 标识特定活动（例如“summer_sale”、“product_launch”）
• term （可选）：UTM 术语参数 - 标识付费搜索术语
• content （可选）：UTM 内容参数 - 区分指向同一 URL 的广告或链接
• keyword （可选）：短网址的自定义关键字
• title （可选）：URL 的标题

基于插件的工具

7. url_analytics

获取指定日期范围内短网址的详细点击分析数据。需要安装 API ShortURL Analytics 插件。

参数：

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

8. contract_url

检查 URL 是否已被缩短，无需创建新的短 URL。需要安装 API Contract 插件。

参数：

• url （必填）：用于检查是否已缩短的 URL

9. 更新网址

更新现有的短网址，使其指向其他目标网址。需要安装 API 编辑网址插件。

参数：

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

10. 更改关键字

更改现有短网址的关键字。需要安装 API Edit URL 插件。

参数：

• oldshorturl （必填）：现有的短网址或关键词
• newshorturl （必需）：要使用的新关键字
• url （可选）：可选 URL（如果未提供，则将使用 oldshorturl 中的 URL）
• title （可选）：可选的新标题（“keep”表示保留现有标题，“auto”表示从 URL 获取）

11. 获取 URL 关键字

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

参数：

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

12. 删除网址

删除短网址。需要安装 API Delete 插件。

参数：

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

13. 列表网址

获取包含排序、分页和筛选选项的 URL 列表。需要安装 API List Extended 插件。

参数：

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

14. 生成二维码

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

参数：

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

使用示例

配置完成后，Claude 将能够使用 YOURLS 工具并提示如下：

核心功能示例

• “帮我缩短这个 URL： https://example.com/very-long-url-that-needs-shortening ”
• “为https://example.com/documentation创建包含关键字‘docs’的短网址”
• “设置指向shapescale.com的自定义URL bysha.pe/web”
• “使用关键字‘docs’为我们的文档创建自定义短网址”
• “为同一个文档 URL 创建多个关键字 (docs、docs2、docs3)”
• “使用 UTM 跟踪参数为我们的广告系列创建一个短 URL”
• “使用 Google Analytics 跟踪缩短此营销 URL：source=newsletter、medium=email、campaign=summer_launch”
• “扩展此短网址： https://yourdomain.com/abc ”
• “我的短网址https://yourdomain.com/abc有多少次点击？”
• “显示我的 YOURLS 实例的统计信息”

基于插件的功能示例

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

发展

工作原理

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

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

该服务器使用模型上下文协议 (MCP) 标准与 Claude Desktop 进行通信，从而实现与您的 URL 缩短器的无缝集成和自然语言交互。

重复 URL 处理

YOURLS-MCP 提供了一项独特的功能，可以为同一个目标网址创建多个短网址，而 YOURLS 原生不支持此功能。有关此功能的详细信息，请参阅重复网址处理文档。

支持两种方法：

1. 插件方法（推荐）：使用包含的强制允许重复插件来创建真正的重复 URL
2. URL 修改方法（后备）：添加时间戳参数，使每个 URL 在技术上唯一，同时保留功能

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

与 YOURLS 插件的兼容性

YOURLS-MCP 旨在与标准 YOURLS 安装和各种插件配合使用，并在插件不可用时提供内置的回退功能：

支持的插件及后备功能

当未安装插件时，YOURLS-MCP 包含扩展功能的智能回退功能：

• API ShortURL Analytics ：提供日期范围的详细点击统计信息
  • 回退行为：当插件不可用时，通过核心 YOURLS API 提供基本的点击统计信息
• API 契约：在不创建 URL 的情况下检查 URL 是否存在
  • 回退行为：使用核心 YOURLS 统计 API 通过过滤搜索现有 URL
• API 编辑 URL ：用于更新短 URL 和更改关键字
  • 后备行为：
    • 对于更新 URL：尝试使用相同的关键字重新创建 URL
    • 更改关键字：使用新关键字创建一个新的短网址（保留旧网址，因为删除需要 API Delete 插件）
    • 获取 URL 关键字：使用核心 YOURLS 统计 API 进行过滤
• API Delete ：用于删除短网址
  • 回退行为：有限 - 提供删除需要插件的信息，因为核心 YOURLS API 不支持删除
• API 列表扩展：用于通过排序和过滤增强 URL 列表
  • 回退行为：使用核心 YOURLS 统计 API 进行客户端排序和分页
• YOURLS-IQRCodes ：用于从短 URL 生成二维码
  • 后备行为：无 - 需要安装插件
• ShortShort ：尝试缩短已缩短的 URL 时正确处理错误
  • 兼容性：无论是否安装插件，错误处理都可以进行
• 允许现有 URL ：修改 YOURLS 处理重复 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. 从插件库下载
    2. 将force-allow-duplicates文件夹复制到YOURLS/user/plugins/目录
    3. 在您的 YOURLS 管理界面中激活该插件

回退机制

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

1. 自动检测缺失的插件
2. 尽可能提供适当的后备功能
3. 当激活回退时，在响应中包含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 产品集成。

强制允许重复插件是为了解决为同一目的地创建多个短 URL 的难题而开发的，而 YOURLS 本身并不支持这一难题。

对于支持、问题或功能请求：

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