{ "markdown": "# Youfiliate MCP Server\n\n\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", "bytes": 7010, "sha": "a7cf22dad3088f8a639b84e40fc1cb471301e01eb77d0fa263a16cdd36afb87c", "repo_slug": "andrewmpierce/youfiliate-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_andrewmpierce_youfiliate_mcp_24d03965/readme" }