YOURLS-MCP

YOURLS-MCP

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

作者： Martin Kessler

概述

YOURLS-MCP 在 Claude Desktop 与你自托管的 YOURLS URL 缩短服务实例之间建立桥接。配置完成后，Claude 可以使用你的个人 YOURLS 安装自动缩短 URL。

功能

• 使用你的 YOURLS 实例缩短 URL
• 使用指定关键词创建自定义短 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
• Windows：%APPDATA%\Claude\config.json
• Linux：~/.config/Claude/config.json

功能

• 通过 MCP 与 Claude Desktop 无缝集成
• 直接通过 Claude 缩短 URL
• 展开短 URL，查看其目标地址
• 获取链接的点击统计数据
• 支持自定义关键词
• 基于签名的安全身份验证
• 环境变量配置

配置选项

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

变量	说明	默认值	必填
YOURLS_API_URL	YOURLS API 端点的 URL	-	是
YOURLS_AUTH_METHOD	身份验证方法（signature 或 password）	signature	否
YOURLS_SIGNATURE_TOKEN	用于基于签名的身份验证的密钥令牌	-	是（使用签名身份验证时）
YOURLS_USERNAME	用于基于密码的身份验证的用户名	-	是（使用密码身份验证时）
YOURLS_PASSWORD	用于基于密码的身份验证的密码	-	是（使用密码身份验证时）
YOURLS_SIGNATURE_TTL	签名的生存时间，单位为秒	43200（12 小时）	否

可用的 MCP 工具

YOURLS-MCP 向 Claude 提供以下工具：

核心工具

1. shorten_url

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

参数：

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

2. expand_url

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

参数：

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

3. url_stats

获取短 URL 的统计数据。

参数：

• shorturl（必填）：要查询统计数据的短 URL 或关键词

4. db_stats

获取 YOURLS 实例的全局统计数据。

参数： 无

5. create_custom_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. shorten_with_analytics

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

参数：

• url（必需）：要缩短的 URL
• source（必需）：UTM 来源参数，用于标识流量来源（例如，“google”“newsletter”“twitter”）
• 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 Analytics 插件。

参数：

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

8. contract_url

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

参数：

• url（必需）：要检查是否已缩短的 URL

9. update_url

更新现有短 URL，使其指向其他目标 URL。 需要安装 API Edit URL 插件。

参数：

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

10. change_keyword

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

参数：

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

11. get_url_keyword

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

参数：

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

12. delete_url

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

参数：

• shorturl（必需）：要删除的短 URL 或关键词

13. list_urls

获取 URL 列表，并提供排序、分页和筛选选项。 需要安装 API List Extended 插件。

参数：

• sortby（可选）：排序字段（keyword、url、title、ip、timestamp、clicks）（默认值：timestamp）
• sortorder（可选）：排序顺序（ASC 或 DESC）（默认值：DESC）
• offset（可选）：分页偏移量（默认值：0）
• perpage（可选）：每页结果数（默认值：50）
• query（可选）：用于按关键词筛选的可选搜索查询
• fields（可选）：要返回的字段（keyword、url、title、timestamp、ip、clicks）（默认值：所有字段）

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”
• “为 https://example.com/documentation 创建一个关键词为 'docs' 的短 URL”
• “设置一个自定义 URL bysha.pe/web，使其指向 shapescale.com”
• “使用关键词 'docs' 为我们的文档创建一个自定义短 URL”
• “为同一个文档 URL 创建多个关键词（docs、docs2、docs3）”
• “为我们的营销活动创建一个带有 UTM 跟踪参数的短 URL”
• “缩短这个带有 Google Analytics 跟踪参数的营销 URL：source=newsletter、medium=email、campaign=summer_launch”
• “展开这个短 URL：https://yourdomain.com/abc”
• “我的短 URL https://yourdomain.com/abc 有多少次点击？”
• “显示我的 YOURLS 实例的统计信息”

基于插件的功能示例

• “提供 shorturl 'abc' 在 2025 年 1 月的详细分析数据”
• “显示 bysha.pe/abc 在 2025-01-01 至 2025-01-31 的点击统计”
• “我的 shortURL 'web' 上个月的每日流量是多少？”
• “检查此 URL 是否已被缩短：https://example.com/page”
• “是否已有人为 https://example.com/page 创建短 URL？”
• “更新短 URL 'docs' 的目标地址，使其指向 https://example.com/new-documentation”
• “更改关键词 'docs' 的指向地址”
• “将短 URL 'docs' 重命名为 'documentation'”
• “将我的短 URL 关键词从 'docs' 改为 'documentation'”
• “这个长 URL 的关键词是什么：https://example.com/page？”
• “列出 https://example.com/page 对应的所有短 URL”
• “删除短 URL 'docs'”
• “从我的 YOURLS 实例中移除关键词 'docs'”
• “显示我的 YOURLS 数据库中最近的 10 个短 URL”
• “按点击次数排序列出所有短 URL”
• “搜索包含 'product' 的短 URL”
• “为我的短 URL 'docs' 生成二维码”
• “为 bysha.pe/web 创建二维码”
• “为我的产品页面生成一个高纠错级别的二维码”
• “我需要更大的 'landing' shorturl 二维码，将其尺寸设为 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

该服务使用 Model Context Protocol（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 Analytics：用于获取指定日期范围内的详细点击统计信息

  • 回退行为：如果插件不可用，则通过 YOURLS 核心 API 提供基本点击统计信息

• API Contract：用于检查 URL 是否存在，而不创建 URL

  • 回退行为：使用 YOURLS 核心 stats API，通过筛选来搜索现有 URL

• API Edit URL：用于更新短 URL 和更改关键词

  • 回退行为：
    • 更新 URL：尝试使用相同关键词重新创建 URL
    • 更改关键词：使用新关键词创建新的短 URL（旧 URL 会保留，因为删除操作需要 API Delete 插件）
    • 获取 URL 关键词：使用 YOURLS 核心 stats API 进行筛选

• API Delete：用于删除短 URL

  • 回退行为：有限——提示删除操作需要安装该插件，因为 YOURLS 核心 API 不支持删除

• API List Extended：用于通过排序和筛选增强 URL 列表功能

  • 回退行为：使用 YOURLS 核心 stats API，并在客户端进行排序和分页

• YOURLS-IQRCodes：用于从短 URL 生成二维码

  • 回退行为：无——必须安装该插件

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

  • 兼容性：无论是否安装该插件，错误处理均可正常工作

• Allow Existing URLs：修改 YOURLS 处理重复 URL 的方式

  • 插件 URL：https://github.com/elder-oss/yourls-allow-existing-urls
  • 注意：此插件会将错误响应改为成功响应，但不会为已有目标 URL 实际创建新的短 URL
  • 我们的解决方案：YOURLS-MCP 采用 URL 修改方式，在 URL 中添加时间戳参数，使其在数据库中保持唯一，同时保留用户体验
  • 安装：可选——无论是否安装此插件，我们的 URL 修改方式都能正常工作

• Force Allow Duplicates：真正支持为同一目标 URL 创建多个短 URL

  • 插件仓库：https://github.com/kesslerio/yourls-force-allow-duplicates（即将推出）
  • 说明：自定义插件，可绕过 YOURLS 的 URL 唯一性约束
  • 用法：在 API 请求中添加 force=1，或对 create_custom_url 工具使用 force_url_modification=false
  • 安装：
    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：测试 Allow Existing URLs 插件的行为

• 插件测试：

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

• 运行测试：

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

实用脚本

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

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

许可证

MIT

关于

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

Force Allow Duplicates 插件旨在解决为同一目标创建多个短网址的难题，而 YOURLS 原生不支持此功能。

如需支持、反馈问题或提交功能请求：

• YOURLS-MCP：https://github.com/kesslerio/yourls-mcp/issues
• Force Allow Duplicates 插件：https://github.com/kesslerio/yourls-force-allow-duplicates/issues（仓库创建后）