youfiliate-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@youfiliate-mcp Create a smart link for https://amazon.com/dp/B09V3KXJPB"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Youfiliate MCP Server
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
pip install youfiliate-mcpRequires 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
Related MCP server: Refgrow MCP Server
Claude Desktop Configuration
Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
Local (stdio)
{
"mcpServers": {
"youfiliate": {
"command": "youfiliate-mcp",
"env": {
"YOUFILIATE_API_KEY": "youfiliate_sk_your_key_here"
}
}
}
}Remote (Streamable HTTP)
{
"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 |
| Create a new geo-targeted smart link |
| List smart links with filtering and pagination |
| Get full details of a smart link by ID |
| Update a smart link (partial update) |
| Delete a smart link (requires |
Analytics (3)
Tool | Description |
| Get click analytics for a specific link |
| Get analytics across all links |
| Trigger a health check on a link |
Preferences (2)
Tool | Description |
| Get default smart link preferences |
| Update preferences for new links |
YouTube (3)
Tool | Description |
| Check YouTube connection status |
| Start YouTube OAuth flow (returns auth URL) |
| Disconnect YouTube (requires |
Migrations (5)
Tool | Description |
| Preview migration scope (dry run) |
| Start YouTube description migration (requires |
| Check migration progress |
| List all migrations |
| Rollback a migration (requires |
Available Resources (4)
URI | Description |
| Dashboard summary (link counts, clicks, health) |
| Current preferences (read-only) |
| Single smart link details |
| Current plan usage and limits |
Example Conversations
Creating a Smart Link
You: Create a smart link for
https://amazon.com/dp/B09V3KXJPBwith geo-targeting for UK and Germany.Claude: (calls
youfiliate_create_smart_linkwith 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_statswithperiod="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_migrationwithconfirm=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 |
| (required) | Your API key |
|
| Backend URL |
| (empty) | Shared secret for verify-api-key (server operators only) |
|
|
|
|
| Port for HTTP transport |
|
| Bind address (use |
Development
git clone https://github.com/andrewmpierce/youfiliate-mcp.git
cd youfiliate-mcp
pip install -e ".[dev]"
pytest -vTest with MCP Inspector
npx @modelcontextprotocol/inspector youfiliate-mcpDocker
docker build -t youfiliate-mcp .
docker run -p 8080:8080 \
-e YOUFILIATE_API_KEY=youfiliate_sk_... \
youfiliate-mcpTroubleshooting
"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
Links
Website: youfiliate.com
Changelog: CHANGELOG.md
Available Tools
18 toolsyoufiliate_check_link_healthARead-onlyIdempotentInspect
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.
Inputs: params (required). Returns: result
youfiliate_connect_youtubeAInspect
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.
Inputs: params (required). Returns: result
youfiliate_create_smart_linkAInspect
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/).
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.
Inputs: params (required). Returns: result
youfiliate_delete_smart_linkADestructiveIdempotentInspect
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.
Inputs: params (required). Returns: result
youfiliate_disconnect_youtubeADestructiveIdempotentInspect
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.
Inputs: params (required). Returns: result
youfiliate_get_aggregate_statsARead-onlyIdempotentInspect
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.
Inputs: params (required). Returns: result
youfiliate_get_migration_statusARead-onlyIdempotentInspect
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.
Inputs: params (required). Returns: result
youfiliate_get_preferencesARead-onlyIdempotentInspect
Get your current smart link preferences/defaults.
Returns default settings applied to newly created smart links. Does NOT create or modify any data.
Inputs: params (required). Returns: result
youfiliate_get_smart_linkARead-onlyIdempotentInspect
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.
Inputs: params (required). Returns: result
youfiliate_get_smart_link_statsARead-onlyIdempotentInspect
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.
Inputs: params (required). Returns: result
youfiliate_get_youtube_statusARead-onlyIdempotentInspect
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_youtubeto connect.
Inputs: params (required). Returns: result
youfiliate_list_migrationsBRead-onlyIdempotentInspect
List your YouTube description migrations with pagination.
Returns a paginated list of all migrations. Does NOT modify any data.
Inputs: params (required). Returns: result
youfiliate_list_smart_linksARead-onlyIdempotentInspect
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.
Inputs: params (required). Returns: result
youfiliate_preview_migrationARead-onlyIdempotentInspect
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.
Inputs: params (required). Returns: result
youfiliate_rollback_migrationADestructiveInspect
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.
Inputs: params (required). Returns: result
youfiliate_start_migrationADestructiveInspect
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.
Inputs: params (required). Returns: result
youfiliate_update_preferencesAIdempotentInspect
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'.
Inputs: params (required). Returns: result
youfiliate_update_smart_linkAIdempotentInspect
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.
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 18 tools
Each tool has a clearly distinct purpose, covering separate actions like CRUD on smart links, YouTube connection management, migration operations, and preferences. There is no overlap or ambiguity.
All tool names follow a consistent pattern: 'youfiliate_' + verb_noun in snake_case (e.g., youfiliate_create_smart_link, youfiliate_get_youtube_status). No deviations or mixed conventions.
With 18 tools, the set is comprehensive yet focused—covering smart link management, migrations, YouTube integration, and preferences. The count is appropriate for the server's scope.
The tool surface covers the full lifecycle of smart links (create, read, update, delete, list, stats, health), migrations (preview, start, status, list, rollback), YouTube connection, and preferences. No obvious gaps.
Maintenance
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Hosted WooCommerce MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Hosted WordPress MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceAn MCP server that provides AI assistants with access to the FirstPromoter affiliate management platform for managing referrals, promoters, campaigns, and commissions. It is designed for remote multi-user deployment and supports operations via HTTP/SSE transport.-
- AlicenseAqualityCmaintenanceMCP server for managing affiliate and referral programs. Track referrals, manage affiliates, process conversions, and handle payouts through AI assistants like Claude, Cursor, and ChatGPT.1881 npm2MIT
- FlicenseAqualityDmaintenanceMCP server for ManyChat API integration that enables Claude and other AI assistants to manage subscribers, tags, custom fields, flows, and send messages through natural language.17-
- AlicenseBqualityDmaintenanceComprehensive MCP server to manage WordPress sites via natural language, enabling content creation, SEO, and multi-site administration through AI tools like Claude Desktop.701,211 npmMIT