Skip to main content
Glama
youfiliate-mcp

youfiliate-mcp

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

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

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)

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)

Tool

Description

youfiliate_get_preferences

Get default smart link preferences

youfiliate_update_preferences

Update preferences for new links

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

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

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

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

Test with 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

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

Available Tools

18 tools
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_disconnect_youtubeA
DestructiveIdempotent
Inspect

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_statsA
Read-onlyIdempotent
Inspect

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_statusA
Read-onlyIdempotent
Inspect

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_preferencesA
Read-onlyIdempotent
Inspect

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_youtube_statusA
Read-onlyIdempotent
Inspect

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.

Inputs: params (required). Returns: result

youfiliate_list_migrationsB
Read-onlyIdempotent
Inspect

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_preview_migrationA
Read-onlyIdempotent
Inspect

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_migrationA
Destructive
Inspect

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_migrationA
Destructive
Inspect

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_preferencesA
Idempotent
Inspect

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 18 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      An 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.
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for managing affiliate and referral programs. Track referrals, manage affiliates, process conversions, and handle payouts through AI assistants like Claude, Cursor, and ChatGPT.
      18
      81 npm
      2
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      MCP 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
      -