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 分