{"id":"1d46df73-b641-401e-956a-5a7091a96f5c","slug":"youfiliate-mcp","kind":"mcp","name":"youfiliate-mcp","summary":"MCP server for Youfiliate Smart Links — manage geo-targeted affiliate links from Claude Desktop and other MCP-compatible AI assistants.","owner":"andrewmpierce","repoUrl":"https://github.com/andrewmpierce/youfiliate-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-04-27T20:53:04.000Z","addedAt":"2026-10-14T05:25:34.641Z","logoUrl":"https://avatars.githubusercontent.com/u/11707173?u=162ce9bcd1d7b5d495b03d5e359e58284006a392&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":[],"runtime":"python","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":true,"reviewed":false,"syncedAt":"2026-10-17T14:43:52.978Z","sample":false,"url":"https://conduits.dev/tools/youfiliate-mcp","language":"Python","transports":["stdio"],"install":{"pypi":"youfiliate-mcp"},"requirements":{"env":[{"name":"YOUFILIATE_API_KEY","secret":true,"required":true,"description":"Your Youfiliate API key (starts with youfiliate_sk_). Generate one at https://youfiliate.com/settings."},{"name":"YOUFILIATE_API_BASE_URL","secret":false,"required":false,"description":"Youfiliate backend URL."}],"upstreamMayCharge":false},"tools":null,"readme":"# Youfiliate MCP Server\n\n<!-- mcp-name: io.github.andrewmpierce/youfiliate-mcp -->\n\n[![PyPI](https://img.shields.io/pypi/v/youfiliate-mcp.svg)](https://pypi.org/project/youfiliate-mcp/)\n[![Python](https://img.shields.io/pypi/pyversions/youfiliate-mcp.svg)](https://pypi.org/project/youfiliate-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nMCP (Model Context Protocol) server for managing [Youfiliate](https://youfiliate.com) 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.\n\n**18 tools, 4 resources, supports stdio + streamable HTTP transports.**\n\n## Installation\n\n```bash\npip install youfiliate-mcp\n```\n\nRequires Python 3.11+ and a [Youfiliate](https://youfiliate.com) account.\n\n### Generate an API key\n\n1. Log in at [youfiliate.com](https://youfiliate.com)\n2. Go to **Settings → API Keys**\n3. Click **Create API Key** (e.g. \"Claude Desktop\")\n4. Copy the key (starts with `youfiliate_sk_`) — shown only once\n\n## Claude Desktop Configuration\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n### Local (stdio)\n\n```json\n{\n  \"mcpServers\": {\n    \"youfiliate\": {\n      \"command\": \"youfiliate-mcp\",\n      \"env\": {\n        \"YOUFILIATE_API_KEY\": \"youfiliate_sk_your_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Remote (Streamable HTTP)\n\n```json\n{\n  \"mcpServers\": {\n    \"youfiliate\": {\n      \"url\": \"https://mcp.youfiliate.com\",\n      \"headers\": {\n        \"Authorization\": \"Bearer youfiliate_sk_your_key_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop after editing the config.\n\n## Available Tools (18)\n\n### Smart Links CRUD (5)\n\n| Tool | Description |\n|------|-------------|\n| `youfiliate_create_smart_link` | Create a new geo-targeted smart link |\n| `youfiliate_list_smart_links` | List smart links with filtering and pagination |\n| `youfiliate_get_smart_link` | Get full details of a smart link by ID |\n| `youfiliate_update_smart_link` | Update a smart link (partial update) |\n| `youfiliate_delete_smart_link` | Delete a smart link (requires `confirm=True`) |\n\n### Analytics (3)\n\n| Tool | Description |\n|------|-------------|\n| `youfiliate_get_smart_link_stats` | Get click analytics for a specific link |\n| `youfiliate_get_aggregate_stats` | Get analytics across all links |\n| `youfiliate_check_link_health` | Trigger a health check on a link |\n\n### Preferences (2)\n\n| Tool | Description |\n|------|-------------|\n| `youfiliate_get_preferences` | Get default smart link preferences |\n| `youfiliate_update_preferences` | Update preferences for new links |\n\n### YouTube (3)\n\n| Tool | Description |\n|------|-------------|\n| `youfiliate_get_youtube_status` | Check YouTube connection status |\n| `youfiliate_connect_youtube` | Start YouTube OAuth flow (returns auth URL) |\n| `youfiliate_disconnect_youtube` | Disconnect YouTube (requires `confirm=True`) |\n\n### Migrations (5)\n\n| Tool | Description |\n|------|-------------|\n| `youfiliate_preview_migration` | Preview migration scope (dry run) |\n| `youfiliate_start_migration` | Start YouTube description migration (requires `confirm=True`) |\n| `youfiliate_get_migration_status` | Check migration progress |\n| `youfiliate_list_migrations` | List all migrations |\n| `youfiliate_rollback_migration` | Rollback a migration (requires `confirm=True`) |\n\n## Available Resources (4)\n\n| URI | Description |\n|-----|-------------|\n| `youfiliate://summary` | Dashboard summary (link counts, clicks, health) |\n| `youfiliate://preferences` | Current preferences (read-only) |\n| `youfiliate://smart-link/{id}` | Single smart link details |\n| `youfiliate://plan-limits` | Current plan usage and limits |\n\n## Example Conversations\n\n### Creating a Smart Link\n\n> **You:** Create a smart link for `https://amazon.com/dp/B09V3KXJPB` with geo-targeting for UK and Germany.\n>\n> **Claude:** *(calls `youfiliate_create_smart_link` with geo rules for GB and DE)*\n>\n> Done. Short URL: `youfil.to/b09v3kxjpb`\n> - US (default): amazon.com/dp/B09V3KXJPB\n> - UK: amazon.co.uk/dp/B09V3KXJPB\n> - Germany: amazon.de/dp/B09V3KXJPB\n\n### Checking Analytics\n\n> **You:** How are my links performing this month?\n>\n> **Claude:** *(calls `youfiliate_get_aggregate_stats` with `period=\"30d\"`)*\n>\n> 1,234 clicks. Top countries: US (500), UK (200), Germany (150). Most traffic from YouTube (900 clicks).\n\n### YouTube Migration\n\n> **You:** Convert all my YouTube description links to smart links.\n>\n> **Claude:** *(calls `youfiliate_preview_migration`)* Would affect 15 videos / 42 links. Proceed?\n>\n> **You:** Yes.\n>\n> **Claude:** *(calls `youfiliate_start_migration` with `confirm=True`)*\n\n## Security Model\n\n1. **API key auth.** Your `youfiliate_sk_...` key authenticates the MCP server.\n2. **JWT bridge.** The server exchanges your API key for short-lived JWTs against the Youfiliate API.\n3. **Token caching.** JWTs are cached in memory and auto-refreshed.\n4. **Scoped data access.** The server only sees data belonging to the API key's owner.\n5. **Destructive actions guarded.** Delete, disconnect, start migration, and rollback require explicit `confirm=True`.\n\n## Rate Limits\n\n- MCP layer: 60 requests/minute per API key\n- Health checks: 1 per link per 5 minutes\n- API key exchange: rate-limited by the Youfiliate backend\n\n## Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `YOUFILIATE_API_KEY` | (required) | Your API key |\n| `YOUFILIATE_API_BASE_URL` | `https://app.youfiliate.com` | Backend URL |\n| `MCP_SERVER_SECRET` | (empty) | Shared secret for verify-api-key (server operators only) |\n| `TRANSPORT` | `stdio` | `stdio` or `streamable-http` |\n| `PORT` | `8080` | Port for HTTP transport |\n| `HOST` | `127.0.0.1` | Bind address (use `0.0.0.0` in Docker) |\n\n## Development\n\n```bash\ngit clone https://github.com/andrewmpierce/youfiliate-mcp.git\ncd youfiliate-mcp\npip install -e \".[dev]\"\npytest -v\n```\n\n### Test with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector youfiliate-mcp\n```\n\n### Docker\n\n```bash\ndocker build -t youfiliate-mcp .\ndocker run -p 8080:8080 \\\n  -e YOUFILIATE_API_KEY=youfiliate_sk_... \\\n  youfiliate-mcp\n```\n\n## Troubleshooting\n\n**\"Authentication failed\"** — verify your API key, regenerate at [youfiliate.com/settings](https://youfiliate.com/settings) if needed.\n\n**\"Could not connect to the Youfiliate API\"** — check `YOUFILIATE_API_BASE_URL`. Defaults to `https://app.youfiliate.com`.\n\n**\"Rate limit exceeded\"** — wait a moment. Health checks are 1 per 5 minutes per link.\n\n**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.\n\n## License\n\n[MIT](LICENSE)\n\n## Links\n\n- Website: [youfiliate.com](https://youfiliate.com)\n- Issues: [github.com/andrewmpierce/youfiliate-mcp/issues](https://github.com/andrewmpierce/youfiliate-mcp/issues)\n- Changelog: [CHANGELOG.md](CHANGELOG.md)\n"}