Youfiliate Smart Links

io.github.andrewmpierce由 GitHub 帳號 andrewmpierce 發布v0.1.1更新於 Oct 24, 2026

Create geo-targeted affiliate smart links, pull analytics, and rewrite YouTube descriptions.

已驗證Streamable HTTP可網頁執行資料與分析商業與電商媒體與設計

概覽

AI 產生的概覽

管理 Youfiliate 聯盟智慧連結：建立地理定向連結、讀取點擊分析，並遷移 YouTube 描述中的連結。

可以做什麼
建立、列出、檢視、更新和刪除帶有國家規則與應用程式深度連結的地理定向智慧連結，並讀取和修改預設連結偏好。讀取單一連結或整個帳戶的點擊分析，並觸發連結健康檢查。透過 OAuth 連結檢視、連接或中斷 YouTube 帳戶。預覽、啟動、追蹤和回復將 YouTube 影片描述改寫為智慧連結的遷移工作。
適用情境
適合已在使用 Youfiliate 的聯盟行銷人員和創作者，希望在對話中而非網頁後台建立、審查和分析智慧連結，或轉換 YouTube 描述中的連結。
執行需求
需要 Youfiliate 帳戶和以 youfiliate_sk_ 開頭的 API 金鑰：本機 Python 3.11+ 套件透過 YOUFILIATE_API_KEY 環境變數提供，遠端端點透過 Authorization 標頭以 Bearer 權杖提供。需要存取 Youfiliate 後端的網路；可用 YOUFILIATE_API_BASE_URL 覆寫基礎位址。
安裝前請注意
API 金鑰可存取帳戶的連結和分析資料，請勿放入共用設定。刪除、中斷 YouTube、啟動遷移和回復屬於破壞性或難以復原的操作，需要明確確認。啟動或回復遷移會改寫 YouTube 影片描述，連接 YouTube 會授予 Youfiliate 對該頻道的 OAuth 存取權限。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Youfiliate Smart Links，將其新增到工作區。
  2. 連接 Authorization token 憑證。它們會被私密儲存，絕不會在公開頁面上展示。
  3. 為需要使用其工具的對話啟用該服務。

Web executable，透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式，或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南，先向你展示發布者、端點和登入方式，經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.andrewmpierce%2Fyoufiliate-mcp/install.md，並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前，先告訴我它的發布者、端點和登入方式，等我確認。不要把 API 金鑰寫進命令或我會提交的檔案；問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

{
  "mcpServers": {
    "youfiliate-smart-links": {
      "type": "http",
      "url": "https://youfiliate-mcp.onrender.com/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

README

Youfiliate MCP Server

[PyPI] [Python] [License: MIT]

MCP (Model Context Protocol) server for managing Youfiliate Smart Links from AI assistants like Claude Desktop. Create geo-targeted affiliate links, view analytics, and run YouTube description migrations — all from a chat conversation.

18 tools, 4 resources, supports stdio + streamable HTTP transports.

Installation

bash
pip install youfiliate-mcp

Requires Python 3.11+ and a Youfiliate account.

Generate an API key

  1. Log in at youfiliate.com
  2. Go to Settings → API Keys
  3. Click Create API Key (e.g. "Claude Desktop")
  4. Copy the key (starts with youfiliate_sk_) — shown only once

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

Local (stdio)

json
{  "mcpServers": {    "youfiliate": {      "command": "youfiliate-mcp",      "env": {        "YOUFILIATE_API_KEY": "youfiliate_sk_your_key_here"      }    }  }}

Remote (Streamable HTTP)

json
{  "mcpServers": {    "youfiliate": {      "url": "https://mcp.youfiliate.com",      "headers": {        "Authorization": "Bearer youfiliate_sk_your_key_here"      }    }  }}

Restart Claude Desktop after editing the config.

Available Tools (18)

Smart Links CRUD (5)

ToolDescription
youfiliate_create_smart_linkCreate a new geo-targeted smart link
youfiliate_list_smart_linksList smart links with filtering and pagination
youfiliate_get_smart_linkGet full details of a smart link by ID
youfiliate_update_smart_linkUpdate a smart link (partial update)
youfiliate_delete_smart_linkDelete a smart link (requires confirm=True)

Analytics (3)

ToolDescription
youfiliate_get_smart_link_statsGet click analytics for a specific link
youfiliate_get_aggregate_statsGet analytics across all links
youfiliate_check_link_healthTrigger a health check on a link

Preferences (2)

ToolDescription
youfiliate_get_preferencesGet default smart link preferences
youfiliate_update_preferencesUpdate preferences for new links

YouTube (3)

ToolDescription
youfiliate_get_youtube_statusCheck YouTube connection status
youfiliate_connect_youtubeStart YouTube OAuth flow (returns auth URL)
youfiliate_disconnect_youtubeDisconnect YouTube (requires confirm=True)

Migrations (5)

ToolDescription
youfiliate_preview_migrationPreview migration scope (dry run)
youfiliate_start_migrationStart YouTube description migration (requires confirm=True)
youfiliate_get_migration_statusCheck migration progress
youfiliate_list_migrationsList all migrations
youfiliate_rollback_migrationRollback a migration (requires confirm=True)

Available Resources (4)

URIDescription
youfiliate://summaryDashboard summary (link counts, clicks, health)
youfiliate://preferencesCurrent preferences (read-only)
youfiliate://smart-link/{id}Single smart link details
youfiliate://plan-limitsCurrent plan usage and limits

Example Conversations

Creating a Smart Link

You: Create a smart link for https://amazon.com/dp/B09V3KXJPB with geo-targeting for UK and Germany.

Claude: (calls youfiliate_create_smart_link with geo rules for GB and DE)

Done. Short URL: youfil.to/b09v3kxjpb

  • US (default): amazon.com/dp/B09V3KXJPB
  • UK: amazon.co.uk/dp/B09V3KXJPB
  • Germany: amazon.de/dp/B09V3KXJPB

Checking Analytics

You: How are my links performing this month?

Claude: (calls youfiliate_get_aggregate_stats with period="30d")

1,234 clicks. Top countries: US (500), UK (200), Germany (150). Most traffic from YouTube (900 clicks).

YouTube Migration

You: Convert all my YouTube description links to smart links.

Claude: (calls youfiliate_preview_migration) Would affect 15 videos / 42 links. Proceed?

You: Yes.

Claude: (calls youfiliate_start_migration with confirm=True)

Security Model

  1. API key auth. Your youfiliate_sk_... key authenticates the MCP server.
  2. JWT bridge. The server exchanges your API key for short-lived JWTs against the Youfiliate API.
  3. Token caching. JWTs are cached in memory and auto-refreshed.
  4. Scoped data access. The server only sees data belonging to the API key's owner.
  5. Destructive actions guarded. Delete, disconnect, start migration, and rollback require explicit confirm=True.

Rate Limits

  • MCP layer: 60 requests/minute per API key
  • Health checks: 1 per link per 5 minutes
  • API key exchange: rate-limited by the Youfiliate backend

Environment Variables

VariableDefaultDescription
YOUFILIATE_API_KEY(required)Your API key
YOUFILIATE_API_BASE_URLhttps://app.youfiliate.comBackend URL
MCP_SERVER_SECRET(empty)Shared secret for verify-api-key (server operators only)
TRANSPORTstdiostdio or streamable-http
PORT8080Port for HTTP transport
HOST127.0.0.1Bind address (use 0.0.0.0 in Docker)

Development

bash
git clone https://github.com/andrewmpierce/youfiliate-mcp.gitcd youfiliate-mcppip install -e ".[dev]"pytest -v

Test with MCP Inspector

bash
npx @modelcontextprotocol/inspector youfiliate-mcp

Docker

bash
docker build -t youfiliate-mcp .docker run -p 8080:8080 \  -e YOUFILIATE_API_KEY=youfiliate_sk_... \  youfiliate-mcp

Troubleshooting

"Authentication failed" — verify your API key, regenerate at youfiliate.com/settings if needed.

"Could not connect to the Youfiliate API" — check YOUFILIATE_API_BASE_URL. Defaults to https://app.youfiliate.com.

"Rate limit exceeded" — wait a moment. Health checks are 1 per 5 minutes per link.

Tools not appearing in Claude Desktop — check claude_desktop_config.json syntax, restart Claude Desktop, run youfiliate-mcp --help to verify the binary is on your PATH.

License

MIT

Links

來源：README.md，提交 8c4bb39

工具

18

youfiliate_get_aggregate_stats

Get Aggregate Stats

Get aggregate click analytics across all your smart links. Returns total clicks, top countries, devices, and referrers across your entire account for the specified period. Does NOT modify any data.

輸入參數params必填

youfiliate_get_preferences

Get Preferences

Get your current smart link preferences/defaults. Returns default settings applied to newly created smart links. Does NOT create or modify any data.

輸入參數params必填

youfiliate_update_preferences

Update Preferences

Update your smart link preferences/defaults. Changes apply to newly created links only — existing links are not affected. Does NOT delete any data. Common errors: - Invalid redirect_type: must be '301' or '302'.

輸入參數params必填

youfiliate_get_youtube_status

Get YouTube Connection Status

Check if your YouTube account is connected. Returns connection status, channel name, and scope information. Does NOT modify any data or initiate any connections. Common errors: - Not connected: use `youfiliate_connect_youtube` to connect.

輸入參數params必填

youfiliate_connect_youtube

Connect YouTube Account

Initiate YouTube OAuth connection. Returns a URL the user must open in their browser. The user must open the returned URL in their web browser to authorize Youfiliate to access their YouTube channel. The OAuth callback is handled in the browser — this tool only returns the authorization URL. Does NOT read or modify any YouTube data. The OAuth flow is completed in the user's browser. Common errors: - Already connected: disconnect first with `youfiliate_disconnect_youtube`.

輸入參數params必填

youfiliate_disconnect_youtube

Disconnect YouTube Account

Disconnect your YouTube account from Youfiliate. IMPORTANT: Always confirm with the user before executing this action. The `confirm` parameter must be set to true. This removes stored OAuth tokens. You will need to reconnect to use the auto-migration feature. Does NOT modify any YouTube data or video descriptions. Common errors: - Not connected: no YouTube account to disconnect. - confirm=False: you must set confirm=True after getting user confirmation.

輸入參數params必填

youfiliate_preview_migration

Preview Migration

Preview a YouTube description migration without making changes. Performs a dry-run analysis showing how many videos and links would be affected. Does NOT modify any data or YouTube descriptions. Requires a connected YouTube account. Common errors: - YouTube not connected: connect first with `youfiliate_connect_youtube`.

輸入參數params必填

youfiliate_start_migration

Start YouTube Migration

Start a YouTube description migration to convert links to smart links. IMPORTANT: This modifies YouTube video descriptions. Always confirm with the user before executing. Describe the scope (number of videos/links affected from the preview) and ask for explicit confirmation. The migration runs asynchronously. Use `youfiliate_get_migration_status` to track progress. Requires a connected YouTube account. Common errors: - YouTube not connected: connect first. - Migration already in progress: wait for it to complete. - confirm=False: must set confirm=True after user confirmation.

輸入參數params必填

youfiliate_get_migration_status

Get Migration Status

Get the status and progress of a specific migration. Returns detailed status including videos processed, links created, and any errors. Does NOT modify any data. Common errors: - Migration not found: check the ID or use `youfiliate_list_migrations`.

輸入參數params必填

youfiliate_list_migrations

List Migrations

List your YouTube description migrations with pagination. Returns a paginated list of all migrations. Does NOT modify any data.

輸入參數params必填

youfiliate_rollback_migration

Rollback Migration

Roll back a completed migration, restoring original YouTube descriptions. IMPORTANT: This modifies YouTube video descriptions. Always confirm with the user before executing. This reverts all video descriptions to their pre-migration state. The rollback runs asynchronously. Requires a connected YouTube account. Common errors: - Migration not found or not in a rollback-eligible state. - YouTube not connected: reconnect first. - confirm=False: must set confirm=True after user confirmation.

輸入參數params必填

版本歷史

1
  1. v0.1.1最新Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分