opn-mcp

opn-mcp

一个适用于 opn.onl 的 MCP 服务。opn.onl 是一款开源、可自托管的 URL 缩短工具。它让 AI 助手（Claude Desktop、Cursor 等）能够通过自然语言缩短链接、查看分析数据、生成二维码和管理链接。

既可使用托管服务，也可连接自己的自托管实例。

设置

1. 获取 API 密钥

在你的 opn.onl 实例中，前往 设置 → API 密钥，创建密钥并复制（密钥以 opn_ 开头，且仅显示一次）。

2. 将服务添加到 MCP 客户端

Claude Desktop — 编辑 claude_desktop_config.json（macOS 上的 ~/Library/Application Support/Claude/，Windows 上的 %APPDATA%\Claude\）：

{
  "mcpServers": {
    "opn": {
      "command": "npx",
      "args": ["-y", "opn-mcp"],
      "env": {
        "OPN_API_KEY": "opn_your_key_here"
      }
    }
  }
}

重启客户端即可。默认情况下，它会连接托管 API（https://l.opn.onl）。

想从源代码运行？将 args 替换为 GitHub 构建版本，配置不变： "args": ["-y", "github:ysalitrynskyi/opn-mcp"]（安装时会进行构建）。

自托管实例

将 OPN_BASE_URL 指向你自己的实例 API 主机：

{
  "mcpServers": {
    "opn": {
      "command": "npx",
      "args": ["-y", "opn-mcp"],
      "env": {
        "OPN_API_KEY": "opn_your_key_here",
        "OPN_BASE_URL": "https://l.your-domain.com"
      }
    }
  }
}

配置

环境变量	必需	默认值	描述
OPN_API_KEY	✅	—	你的 API 密钥（opn_…），可在“设置 → API 密钥”中获取
OPN_BASE_URL	—	https://l.opn.onl	API 基础 URL — 自托管实例请设置此项

工具

链接

工具	描述
shorten_url	创建短链接 — 可选别名、标题、备注、定时设置（starts_at/expires_at）、max_clicks、密码、阅后即焚、文件夹和标签
shorten_urls_bulk	一次缩短多个 URL，可选择放入文件夹
list_links	列出你的链接（限制数量、偏移量、搜索、文件夹或标签筛选）
update_link	更新目标地址、标题、备注、定时设置、点击次数上限、文件夹或保护设置；使用 remove_* 标记清除字段
delete_link	删除链接
clone_link	使用新的短代码复制链接
toggle_link_pin	置顶或取消置顶链接
check_alias_available	使用自定义别名前，检查该别名是否可用

分析

工具	描述
get_link_stats	单个链接的分析数据（点击量、独立访客、地理位置、城市、设备、浏览器、操作系统、引荐来源）；可选 days 时间范围
get_dashboard_stats	你的所有链接的账户级分析数据

二维码和 URL 辅助工具

工具	描述
get_qr_code	获取链接的二维码图片 — 可选品牌颜色、中心 Logo、PNG/SVG
check_url_health	缩短前检查目标 URL 是否可访问
build_utm_url	为 URL 添加 UTM 活动参数
preview_url_metadata	获取 URL 的 Open Graph 元数据（标题、描述、图片）

标签和文件夹

工具	描述
list_tags / create_tag	列出或创建标签
add_tags_to_link / remove_tags_from_link	为链接添加或移除标签
list_folders / create_folder	列出或创建文件夹
move_links_to_folder	将链接移至文件夹

示例提示词

• “缩短 https://example.com/very/long/url，并将其命名为 launch-2026”
• “将这五个 URL 缩短，并放入一个名为 Q3 Campaign 的新文件夹”
• “链接 42 在过去 30 天内获得了多少次点击？这些点击来自哪些国家？”
• “为链接 42 生成带品牌标识的 SVG 二维码”
• “将我最近 10 个链接标记为 'newsletter'，并显示我的仪表板统计数据”
• “为 https://example.com 创建 UTM 链接 — 来源为 newsletter，媒介为 email”

开发

npm install
npm run build      # tsc → dist/
npm test           # vitest
OPN_API_KEY=opn_… npm run dev   # run from source (stdio)

发布

这三个注册表都由 ysalitrynskyi（npm 用户、GitHub 用户和 io.github.ysalitrynskyi MCP 注册表命名空间）所有，因此必须使用该账号登录后才能发布。

1. 在三个位置更新版本号，并确保它们一致： package.json、server.json（顶层以及packages[0].version） 和 src/server.ts 中的 SERVER_VERSION。
2. 合并变更：提交到 main 并推送。CI（.github/workflows/ci.yml）会运行 build + test，但不会发布。
3. 发布到 npm（使用 npm 用户 ysalitrynskyi）：

   npm login
   npm publish        # prepublishOnly runs the build
   

4. 发布到 MCP 注册表（使用 GitHub 用户 ysalitrynskyi）：

   mcp-publisher validate      # optional, offline check
   mcp-publisher login github  # interactive browser OAuth
   mcp-publisher publish
   

Smithery（smithery.yaml）和 Glama （glama.json）会自动跟踪 npm/注册表发布，无需单独操作。

许可证

MIT © ysalitrynskyi。属于 opn.onl 项目。