YOURLS-MCP

YOURLS-MCP

Claude Desktop と YOURLS の URL 短縮を連携するための Model Control Protocol（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 の source パラメーター。トラフィックの流入元を識別します（例：「google」、「newsletter」、「twitter」）
• medium（必須）：UTM の medium パラメーター。マーケティングの媒体を識別します（例：「cpc」、「social」、「email」）
• campaign（必須）：UTM の campaign パラメーター。特定のキャンペーンを識別します（例：「summer_sale」、「product_launch」）
• term（任意）：UTM の term パラメーター。有料検索キーワードを識別します
• content（任意）：UTM の content パラメーター。同じ 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」、URL から取得する場合は「auto」）

10. change_keyword

既存の短縮 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. 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（任意）：1 ページあたりの結果数（デフォルト：50）
• query（任意）：キーワードで絞り込むための検索クエリ
• fields（任意）：返すフィールド（keyword、url、title、timestamp、ip、clicks）（デフォルト：すべてのフィールド）

14. generate_qr_code

短縮 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 の短縮 URL を、キーワード docs で作成してください」
• 「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 インスタンスの統計情報を表示してください」

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

• 「短縮 URL abc の 2025 年 1 月の詳細な分析情報を表示してください」
• 「2025-01-01 から 2025-01-31 までの bysha.pe/abc のクリック統計を表示してください」
• 「先月の短縮 URL 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 データベース内の最新の短縮 URL を 10 件表示してください」
• 「クリック数順に、すべての短縮 URL を一覧表示してください」
• 「product を含む短縮 URL を検索してください」
• 「短縮 URL docs の QR コードを生成してください」
• 「bysha.pe/web の QR コードを作成してください」
• 「商品ページ用に、誤り訂正レベルの高い QR コードを作成してください」
• 「短縮 URL landing 用に、300 ピクセルの大きな QR コードを作成してください」
• 「ドキュメントのリンク用に、SVG QR コードを生成してください」

開発

# 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 には、YOURLS で標準ではサポートされていない、同じ転送先 URL に対して複数の短縮 URL を作成できる独自の機能があります。この機能の詳細については、URL の重複処理に関するドキュメントを参照してください。

次の 2 つの方法がサポートされています。

1. プラグイン方式（推奨）：同じ URL の重複作成を許可する付属の Force Allow Duplicates プラグインを使用します
2. URL 変更方式（代替）：タイムスタンプパラメーターを追加することで、機能を保ったまま各 URL を技術的に一意にします

システムは、YOURLS の設定に応じて適切な方法を自動的に選択します。

YOURLS プラグインとの互換性

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

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

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

• API ShortURL Analytics：期間を指定した詳細なクリック統計情報を取得します

  • フォールバックの動作：プラグインが利用できない場合、YOURLS のコア API を通じて基本的なクリック統計情報を提供します

• API Contract：URL を作成せずに、存在するかどうかを確認します

  • フォールバックの動作：YOURLS のコア Stats API を使い、フィルタリングして既存の URL を検索します

• API Edit URL：短縮 URL を更新し、キーワードを変更します

  • フォールバックの動作：
    • URL を更新する場合：同じキーワードで URL の再作成を試みます
    • キーワードを変更する場合：新しいキーワードで短縮 URL を作成します（削除には API Delete プラグインが必要なため、古い URL は残ります）
    • URL のキーワードを取得する場合：YOURLS のコア Stats API をフィルタリングして使います

• API Delete：短縮 URL を削除します

  • フォールバックの動作：制限があります。YOURLS のコア API は削除に対応していないため、削除にはプラグインが必要であることを知らせます

• API List Extended：並べ替えとフィルタリングを使って URL の一覧表示を拡張します

  • フォールバックの動作：YOURLS のコア Stats API を使い、クライアント側で並べ替えとページネーションを行います

• YOURLS-IQRCodes：短縮 URL から QR コードを生成します

  • フォールバックの動作：ありません。プラグインのインストールが必要です

• 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：指定した宛先へのランダムな短縮 URL を作成します
• 特定の URL 作成タスク用のその他のスクリプト

ライセンス

MIT

概要

YOURLS-MCP は、Model Context Protocol（MCP）を介して YOURLS を Claude Desktop やその他の Claude 製品と連携するために、Martin Kessler が作成しました。

Force Allow Duplicates プラグインは、YOURLS では標準でサポートされていない、同じ宛先に対して複数の短縮 URL を作成するという課題を解決するために開発されました。

サポート、問題の報告、機能のリクエストについては、以下をご覧ください。

• YOURLS-MCP：https://github.com/kesslerio/yourls-mcp/issues
• Force Allow Duplicates プラグイン：https://github.com/kesslerio/yourls-force-allow-duplicates/issues（リポジトリ作成後）