Youfiliate Smart Links

io.github.andrewmpiercePublished by GitHub account andrewmpiercev0.1.1Updated Oct 24, 2026

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

VerifiedStreamable HTTPWeb executableData & Analytics Business & Commerce Media & Design

Server details

Identifier: io.github.andrewmpierce/youfiliate-mcp
Transport: Streamable HTTP
Runtime: Web executable
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account andrewmpierce for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.andrewmpierce%2Fyoufiliate-mcp.svg)](https://sourceweft.com/mcp/io.github.andrewmpierce%2Fyoufiliate-mcp?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Manages Youfiliate affiliate smart links: create geo-targeted links, read click analytics, and migrate YouTube description links.

What you can do: Create, list, inspect, update and delete geo-targeted smart links with optional country rules and app deep links, plus read and change default link preferences. Read click analytics per link or across the account, and trigger link health checks. Check, connect or disconnect a YouTube account through an OAuth URL. Preview, start, track and roll back migrations that rewrite YouTube video descriptions to use smart links.
When to use it: Useful for affiliate marketers and creators who already use Youfiliate and want to build, audit and analyze smart links, or convert links in YouTube descriptions, from a chat conversation instead of the web dashboard.
Requirements: A Youfiliate account and an API key starting with youfiliate_sk_, supplied as the YOUFILIATE_API_KEY environment variable for the local Python 3.11+ package or as a Bearer token in the Authorization header for the remote endpoint. Network access to the Youfiliate backend; the base URL can be overridden with YOUFILIATE_API_BASE_URL.

Before you install

The API key grants access to the account's links and analytics; keep it out of shared configs. Delete, YouTube disconnect, migration start and rollback are destructive or hard to undo and require explicit confirmation. Starting a migration or rolling one back rewrites YouTube video descriptions, and connecting YouTube grants Youfiliate OAuth access to the channel.

Installation

In SourceWeft

Open Youfiliate Smart Links in the dashboard and add it to a workspace.
Connect Authorization token credentials. They are stored privately and never shown on public pages.
Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.andrewmpierce%2Fyoufiliate-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "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

Requires Python 3.11+ and a Youfiliate account.

Generate an API key

Log in at youfiliate.com
Go to Settings → API Keys
Click Create API Key (e.g. "Claude Desktop")
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"      }    }  }}

{  "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"      }    }  }}

{  "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)

Tool	Description
`youfiliate_create_smart_link`	Create a new geo-targeted smart link
`youfiliate_list_smart_links`	List smart links with filtering and pagination
`youfiliate_get_smart_link`	Get full details of a smart link by ID
`youfiliate_update_smart_link`	Update a smart link (partial update)
`youfiliate_delete_smart_link`	Delete a smart link (requires `confirm=True`)

Analytics (3)

Tool	Description
`youfiliate_get_smart_link_stats`	Get click analytics for a specific link
`youfiliate_get_aggregate_stats`	Get analytics across all links
`youfiliate_check_link_health`	Trigger a health check on a link

Preferences (2)

YouTube (3)

Tool	Description
`youfiliate_get_youtube_status`	Check YouTube connection status
`youfiliate_connect_youtube`	Start YouTube OAuth flow (returns auth URL)
`youfiliate_disconnect_youtube`	Disconnect YouTube (requires `confirm=True`)

Migrations (5)

Tool	Description
`youfiliate_preview_migration`	Preview migration scope (dry run)
`youfiliate_start_migration`	Start YouTube description migration (requires `confirm=True`)
`youfiliate_get_migration_status`	Check migration progress
`youfiliate_list_migrations`	List all migrations
`youfiliate_rollback_migration`	Rollback a migration (requires `confirm=True`)

Available Resources (4)

URI	Description
`youfiliate://summary`	Dashboard summary (link counts, clicks, health)
`youfiliate://preferences`	Current preferences (read-only)
`youfiliate://smart-link/{id}`	Single smart link details
`youfiliate://plan-limits`	Current 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

API key auth. Your youfiliate_sk_... key authenticates the MCP server.
JWT bridge. The server exchanges your API key for short-lived JWTs against the Youfiliate API.
Token caching. JWTs are cached in memory and auto-refreshed.
Scoped data access. The server only sees data belonging to the API key's owner.
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

Variable	Default	Description
`YOUFILIATE_API_KEY`	(required)	Your API key
`YOUFILIATE_API_BASE_URL`	`https://app.youfiliate.com`	Backend URL
`MCP_SERVER_SECRET`	(empty)	Shared secret for verify-api-key (server operators only)
`TRANSPORT`	`stdio`	`stdio` or `streamable-http`
`PORT`	`8080`	Port for HTTP transport
`HOST`	`127.0.0.1`	Bind 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

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

Test with MCP Inspector

Docker

bash

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

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

Tools

youfiliate_create_smart_link

Create Smart Link

Create a new geo-targeted smart link with an optional custom slug. Creates a smart link that redirects visitors to the destination URL. Optionally configure country-specific geo rules and deep linking for iOS/Android apps. Does NOT modify any existing links. Returns the created smart link details including its short URL (youfil.to/<slug>). Common errors: - Slug already taken: choose a different slug or omit for auto-generation. - Plan limit reached: upgrade your plan to create more links. - Invalid URL: ensure the destination URL is a valid HTTP/HTTPS URL.

Parametersparamsrequired

youfiliate_list_smart_links

List Smart Links

List your smart links with optional filtering, search, and pagination. Returns a paginated list of smart links. Use filters to narrow results. Does NOT create or modify any links. Args: params: Filters include health_status, search (title/URL), ordering, limit (1-100, default 20), and offset. Common errors: - No links found: you may not have created any links yet.

Parametersparamsrequired

youfiliate_get_smart_link

Get Smart Link Details

Get full details of a single smart link by ID. Returns all configuration including geo rules, deep link config, and click stats. Does NOT modify the link. Common errors: - Smart link not found: check the ID or use `youfiliate_list_smart_links`.

Parametersparamsrequired

youfiliate_update_smart_link

Update Smart Link

Update an existing smart link (partial update — only provided fields change). You can update the destination URL, slug, title, redirect type, geo rules, or deep link config. Geo rules are replaced entirely (not merged). Does NOT delete the link. Common errors: - Smart link not found: check the ID. - Slug already taken: choose a different slug.

Parametersparamsrequired

youfiliate_delete_smart_link

Delete Smart Link

Delete a smart link permanently. The short URL will stop working. IMPORTANT: Always confirm with the user before executing this action. The `confirm` parameter must be set to true. This is a destructive action that cannot be undone — the slug becomes available for reuse after a cooldown period. Does NOT affect other links or YouTube descriptions. Common errors: - Smart link not found: check the ID. - confirm=False: you must set confirm=True after getting user confirmation.

Parametersparamsrequired

youfiliate_get_smart_link_stats

Get Smart Link Stats

Get click analytics for a specific smart link. Returns click counts broken down by country, device, referrer, and day for the specified period. Does NOT modify any data. Common errors: - Smart link not found: check the ID.

Parametersparamsrequired

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.

Parametersparamsrequired

youfiliate_check_link_health

Check Link Health

Trigger a health check for a specific smart link. Checks the default URL and all geo-rule URLs for availability. Returns the health status (healthy/broken/unknown). Rate limited to once per 5 minutes per link. Does NOT modify the link configuration. Common errors: - Rate limit: wait 5 minutes between health checks for the same link. - Smart link not found: check the ID.

Parametersparamsrequired

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.

Parametersparamsrequired

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'.

Parametersparamsrequired

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.

Parametersparamsrequired

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`.

Parametersparamsrequired

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.

Parametersparamsrequired

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`.

Parametersparamsrequired

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.

Parametersparamsrequired

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`.

Parametersparamsrequired

youfiliate_list_migrations

List Migrations

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

Parametersparamsrequired

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.

Parametersparamsrequired

Version history

v0.1.1LatestSep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 daysRequired25 pts
Auth declaredRequired10 pts
Tools listedRequired15 pts
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts

Tool	Description
`youfiliate_get_preferences`	Get default smart link preferences
`youfiliate_update_preferences`	Update preferences for new links