opn-mcp

opn-mcp

opn.onl 用の MCP サーバーです。opn.onl はオープンソースで、セルフホスト可能な URL 短縮サービスです。AI アシスタント（Claude Desktop、Cursor など）を使って、自然言語でリンクの短縮、分析データの閲覧、QR コードの生成、リンクの管理ができます。

ホスト型サービスと、独自のセルフホストインスタンスのどちらでも動作します。

セットアップ

1. API キーを取得する

opn.onl のインスタンスで、Settings → API Keys を開き、キーを作成してコピーします（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	✅	—	Settings → API Keys で取得した API キー（opn_…）
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	リンクごとの分析データ（クリック数、ユニーク訪問者数、地域、都市、デバイス、ブラウザー、OS、参照元）を取得します。days で期間を指定できます
get_dashboard_stats	すべてのリンクを対象としたアカウント全体の分析データを取得します

QR コードと URL のヘルパー

ツール	説明
get_qr_code	リンクの QR コード画像を取得します。ブランドカラー、中央ロゴ、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 という名前にして」
• 「この5つの URL を、Q3 Campaign という新しいフォルダーにまとめて短縮して」
• 「リンク42は過去30日間で何回クリックされましたか？また、どの国からですか？」
• 「リンク42のブランド付き SVG QR コードを作成して」
• 「直近10件のリンクに 'newsletter' タグを付けて、ダッシュボードの分析データを表示して」
• 「https://example.com の UTM リンクを作成して。source は newsletter、medium は email」

開発

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

リリース

3 つのレジストリはいずれも ysalitrynskyi（npm ユーザー、GitHub ユーザー、および io.github.ysalitrynskyi MCP レジストリの名前空間）が所有しているため、公開は このアカウントにサインインした状態で行う必要があります。

1. 次の3 か所のバージョンを更新し、すべて同じ値にします。 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 プロジェクトの一部です。