YOURLS-MCP

YOURLS-MCP

YOURLS URL 短縮を Claude Desktop と統合するためのモデル制御プロトコル (MCP) サーバー。

**著者:**マーティン・ケスラー

概要

YOURLS-MCPは、 Claude Desktopとセルフホスト型のYOURL短縮サービスインスタンス間のブリッジを構築します。設定が完了すると、ClaudeはYOURLSを使用してURLを自動的に短縮できるようになります。

特徴

• YOURLSインスタンスを使用してURLを短縮する
• 特定のキーワードでカスタム短縮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. URLを短縮する

YOURLS インスタンスを使用して長い URL を短縮します。

パラメータ:

• url (必須): 短縮する長いURL
• keyword （オプション）：短縮URLのカスタムキーワード
• title (オプション): URLのタイトル

2. 展開URL

短い URL を展開して元の長い URL を取得します。

パラメータ:

• shorturl (必須): 展開する短縮URLまたはキーワード

3. url_stats

短縮 URL の統計を取得します。

パラメータ:

• shorturl (必須): 統計情報を取得する短縮URLまたはキーワード

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」、「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. 契約URL

新しい短縮URLを作成せずに、URLが既に短縮されているかどうかを確認します。API Contractプラグインがインストールされている必要があります。

パラメータ:

• url (必須): 短縮されているかどうかを確認するURL

9. 更新URL

既存の短縮URLを更新して、別のリンク先URLを指定します。API Edit URLプラグインがインストールされている必要があります。

パラメータ:

• shorturl (必須): 更新する短縮URLまたはキーワード
• url (必須): 新しいリンク先URL
• title （オプション）: オプションの新しいタイトル（既存のタイトルを保持する場合は「keep」、URL から取得する場合は「auto」）

10. キーワードの変更

既存の短縮URLのキーワードを変更します。API Edit URLプラグインがインストールされている必要があります。

パラメータ:

• oldshorturl (必須): 既存の短縮URLまたはキーワード
• newshorturl (必須): 使用する新しいキーワード
• url (オプション): オプションの URL (指定されていない場合は、oldshorturl の URL が使用されます)
• title （オプション）: オプションの新しいタイトル（既存のタイトルを保持する場合は「keep」、URL から取得する場合は「auto」）

11. get_url_keyword

長いURLのキーワードを取得します。API Edit URLプラグインがインストールされている必要があります。

パラメータ:

• url (必須): 検索する長いURL
• exactly_one (オプション): false の場合、この URL のすべてのキーワードを返します (デフォルト: true)

12. 削除URL

短縮 URL を削除します。API削除プラグインがインストールされている必要があります。

パラメータ:

• shorturl (必須): 削除する短縮URLまたはキーワード

13. リストURL

並べ替え、ページ区切り、フィルタリングオプション付きのURLリストを取得します。API List Extendedプラグインのインストールが必要です。

パラメータ:

• sortby (オプション): 並べ替えるフィールド (キーワード、URL、タイトル、IP、タイムスタンプ、クリック数) (デフォルト: タイムスタンプ)
• sortorder (オプション): ソート順 (ASC または DESC) (デフォルト: DESC)
• offset （オプション）：ページ区切りのオフセット（デフォルト：0）
• perpage （オプション）：1ページあたりの結果数（デフォルト：50）
• query （オプション）: キーワードでフィルタリングするためのオプションの検索クエリ
• fields (オプション): 返されるフィールド (キーワード、URL、タイトル、タイムスタンプ、IP、クリック数) (デフォルト: すべてのフィールド)

14. QRコードを生成する

短縮URLのQRコードを生成します。YOURLS -IQRCodesプラグインがインストールされている必要があります。

パラメータ:

• shorturl (必須): QRコードを生成するための短縮URLまたはキーワード
• size （オプション）: QRコードのサイズ（ピクセル単位）
• border （オプション）: QRコードの周囲の境界線の幅
• 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 を作成します」
• 「shapescale.com を指すカスタム URL bysha.pe/web を設定します」
• 「キーワード「docs」を使用して、ドキュメントのカスタム短縮 URL を作成します」
• 「同じドキュメント URL に複数のキーワード (docs、docs2、docs3) を作成する」
• 「UTMトラッキングパラメータを使用してキャンペーンの短縮URLを作成する」
• 「Google アナリティクス トラッキングを使用してこのマーケティング URL を短縮します: source=newsletter、medium=email、campaign=summer_launch」
• 「この短縮URLを展開してください： https://yourdomain.com/abc 」
• 「私の短縮 URL https://yourdomain.com/abcは何回クリックされていますか？」
• 「YOURLSインスタンスの統計情報を表示してください」

プラグインベースの機能の例

• 「2025年1月の短縮URL「abc」の詳細な分析を教えてください」
• 「2025年1月1日から2025年1月31日までのbysha.pe/abcのクリック統計を表示してください」
• 「先月の私の短縮 URL「ウェブ」の毎日のトラフィックはどれくらいでしたか？」
• 「この 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をすべて一覧表示する」
• 「「製品」を含む短縮URLを検索」
• 「短縮URL「docs」のQRコードを生成する」
• 「bysha.pe/webのQRコードを作成」
• 「商品ページ用のエラー訂正率の高いQRコードを作成してください」
• 「ランディングページのショートURLにもっと大きなQRコードが必要です。300ピクセルにしてください」
• 「ドキュメントリンク用のSVG QRコードを生成する」

発達

仕組み

YOURLS-MCP は、Claude Desktop と YOURLS インスタンス間のブリッジとして機能します。

1. Claude Desktopは必要に応じてYOURLS-MCPサーバーを起動します
2. サーバーは環境変数から設定を読み取ります
3. クロードがツールを呼び出すと、サーバーはYOURLSインスタンスに適切なAPI呼び出しを行います。
4. 結果は構造化された形式でクロードに返されます

サーバーは、Model Context Protocol (MCP) 標準を使用して Claude Desktop と通信し、URL 短縮機能とのシームレスな統合と自然言語による対話を可能にします。

重複URLの処理

YOURLS-MCPは、同じリンク先URLに対して複数の短縮URLを作成する独自の機能を提供します。これはYOURLSではネイティブサポートされていません。この機能の詳細については、重複URL処理に関するドキュメントをご覧ください。

次の 2 つのアプローチがサポートされています。

1. プラグインアプローチ（推奨）：付属のForce Allow Duplicatesプラグインを使用して、真の重複URLを作成します。
2. URL変更アプローチ（フォールバック）：タイムスタンプパラメータを追加して、機能性を維持しながら各URLを技術的に一意にする

システムは YOURLS の設定に基づいて適切なアプローチを自動的に選択します。

YOURLSプラグインとの互換性

YOURLS-MCP は、標準の YOURLS インストールとさまざまなプラグインの両方で動作するように設計されており、プラグインが利用できない場合はフォールバックが組み込まれています。

フォールバック対応プラグイン

YOURLS-MCP には、プラグインがインストールされていない場合に拡張機能を実現するためのインテリジェントなフォールバックが含まれています。

• APIショートURL分析:日付範囲の詳細なクリック統計
  • フォールバック動作: プラグインが利用できない場合は、コア YOURLS API を通じて基本的なクリック統計を提供します。
• API 契約: URL を作成せずに存在するかどうかを確認する
  • フォールバック動作: コアYOURLS統計APIを使用してフィルタリングされた既存のURLを検索します
• API 編集 URL : 短縮 URL の更新とキーワードの変更
  • フォールバック動作:
    • URLを更新する場合: 同じキーワードでURLを再作成しようとします
    • キーワードを変更する場合: 新しいキーワードで新しい短縮 URL を作成します (削除には API 削除プラグインが必要なので、古い URL は残ります)
    • URLキーワードを取得するには：フィルタリング機能を備えたコアYOURLS統計APIを使用します
• API削除:短縮URLを削除する
  • フォールバック動作: 限定的 - コア YOURLS API が削除をサポートしていないため、削除にはプラグインが必要であるという情報を提供します
• APIリスト拡張:並べ替えとフィルタリングによるURLリストの拡張
  • フォールバック動作: クライアント側の並べ替えとページ区切りを備えたコア YOURLS 統計 API を使用します
• YOURLS-IQRCodes : 短縮URLからQRコードを生成する
  • フォールバック動作: なし - プラグインのインストールが必要
• 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 制約を回避するカスタム プラグイン
  • 使用方法: 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 : 既存の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 ではネイティブにサポートされていない、同じ宛先に複数の短縮 URL を作成するという課題を解決するために開発されました。

サポート、問題、機能リクエストについては、次のアドレスまでお問い合わせください。

• YOURLS-MCP: https://github.com/kesslerio/yourls-mcp/issues
• 重複を強制的に許可するプラグイン: https://github.com/kesslerio/yourls-force-allow-duplicates/issues (リポジトリが作成されたら)