Youfiliate

Youfiliate MCP 服务

用于通过 Claude Desktop 等 AI 助手管理 Youfiliate Smart Links 的 MCP（Model Context Protocol）服务。创建地理位置定向联盟链接、查看分析数据，以及执行 YouTube 简介迁移——所有操作都可以在聊天对话中完成。

18 个工具、4 个资源，支持 stdio 和 streamable HTTP 传输方式。

安装

pip install youfiliate-mcp

需要 Python 3.11+ 和 Youfiliate 账户。

生成 API 密钥

1. 在 youfiliate.com 登录
2. 前往 Settings → API Keys
3. 点击 Create API Key（例如“Claude Desktop”）
4. 复制密钥（以 youfiliate_sk_ 开头）——密钥只会显示一次

Claude Desktop 配置

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

本地（stdio）

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

远程（Streamable HTTP）

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

编辑配置后，重启 Claude Desktop。

可用工具（18 个）

Smart Links 增删改查（5 个）

工具	描述
youfiliate_create_smart_link	创建新的地理位置定向智能链接
youfiliate_list_smart_links	筛选并分页列出智能链接
youfiliate_get_smart_link	根据 ID 获取智能链接的完整详情
youfiliate_update_smart_link	更新智能链接（部分更新）
youfiliate_delete_smart_link	删除智能链接（需要 confirm=True）

分析数据（3 个）

工具	描述
youfiliate_get_smart_link_stats	获取特定链接的点击分析数据
youfiliate_get_aggregate_stats	获取所有链接的综合分析数据
youfiliate_check_link_health	对链接触发健康检查

偏好设置（2 个）

工具	描述
youfiliate_get_preferences	获取默认智能链接偏好设置
youfiliate_update_preferences	更新新链接的偏好设置

YouTube（3 个）

工具	描述
youfiliate_get_youtube_status	检查 YouTube 连接状态
youfiliate_connect_youtube	启动 YouTube OAuth 流程（返回授权 URL）
youfiliate_disconnect_youtube	断开 YouTube 连接（需要 confirm=True）

迁移（5 个）

工具	描述
youfiliate_preview_migration	预览迁移范围（试运行）
youfiliate_start_migration	开始 YouTube 简介迁移（需要 confirm=True）
youfiliate_get_migration_status	检查迁移进度
youfiliate_list_migrations	列出所有迁移
youfiliate_rollback_migration	回滚迁移（需要 confirm=True）

可用资源（4 个）

URI	描述
youfiliate://summary	控制面板摘要（链接数量、点击量、健康状况）
youfiliate://preferences	当前偏好设置（只读）
youfiliate://smart-link/{id}	单个智能链接的详情
youfiliate://plan-limits	当前套餐的用量和限制

对话示例

创建智能链接

你： 为 https://amazon.com/dp/B09V3KXJPB 创建一个智能链接，定向到英国和德国。

Claude： （调用 youfiliate_create_smart_link，设置 GB 和 DE 的地理规则）

已完成。短链接：youfil.to/b09v3kxjpb

• 美国（默认）：amazon.com/dp/B09V3KXJPB
• 英国：amazon.co.uk/dp/B09V3KXJPB
• 德国：amazon.de/dp/B09V3KXJPB

查看分析数据

你： 我的链接这个月的表现如何？

Claude： （调用 youfiliate_get_aggregate_stats，并设置 period="30d"）

1,234 次点击。访问量最高的国家：美国（500 次）、英国（200 次）、德国（150 次）。流量主要来自 YouTube（900 次点击）。

YouTube 迁移

你： 将我 YouTube 描述中的所有链接转换为智能链接。

Claude： （调用 youfiliate_preview_migration） 将影响 15 个视频／42 个链接。是否继续？

你： 是。

Claude： （调用 youfiliate_start_migration，并设置 confirm=True）

安全模型

1. API 密钥身份验证。 你的 youfiliate_sk_... 密钥用于验证 MCP 服务。
2. JWT 桥接。 服务使用你的 API 密钥向 Youfiliate API 换取短期 JWT。
3. 令牌缓存。 JWT 会缓存在内存中，并自动刷新。
4. 限定范围的数据访问。 服务只能查看属于该 API 密钥所有者的数据。
5. 破坏性操作受到保护。 删除、断开连接、开始迁移和回滚操作都需要显式设置 confirm=True。

速率限制

• MCP 层：每个 API 密钥每分钟 60 个请求
• 健康检查：每个链接每 5 分钟 1 次
• API 密钥换取：受 Youfiliate 后端的速率限制

环境变量

变量	默认值	描述
YOUFILIATE_API_KEY	（必填）	你的 API 密钥
YOUFILIATE_API_BASE_URL	https://app.youfiliate.com	后端 URL
MCP_SERVER_SECRET	（空）	用于 verify-api-key 的共享密钥（仅限服务运营者）
TRANSPORT	stdio	stdio 或 streamable-http
PORT	8080	HTTP 传输使用的端口
HOST	127.0.0.1	绑定地址（在 Docker 中使用 0.0.0.0）

开发

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

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector youfiliate-mcp

Docker

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

故障排除

“身份验证失败” — 请检查你的 API 密钥；如有需要，可前往 youfiliate.com/settings 重新生成。

“无法连接到 Youfiliate API” — 请检查 YOUFILIATE_API_BASE_URL。默认值为 https://app.youfiliate.com。

“超出速率限制” — 请稍等片刻。每个链接每 5 分钟可进行 1 次健康检查。

Claude Desktop 中未显示工具 — 请检查 claude_desktop_config.json 语法，重启 Claude Desktop，并运行 youfiliate-mcp --help，以确认二进制文件位于 PATH 中。

许可证

MIT

链接

• 网站：youfiliate.com
• 问题：github.com/andrewmpierce/youfiliate-mcp/issues
• 更新日志：CHANGELOG.md