yhn-mcp

Model Context Protocol server for y.hn. Lets Claude Code, Cursor, Cline, and any other MCP-aware AI agent create and manage short links by talking to the y.hn API.

Quick start

1. Generate an API key at https://y.hn/dashboard/settings.
2. Add the server to your MCP client config (examples below).
3. Restart the client. Type something like "Shorten https://example.com with custom slug demo" — the agent now has tools.

No global install needed; npx fetches the package on demand.

Claude Code

Add to ~/.claude.json (or your project .mcp.json):

{
  "mcpServers": {
    "yhn": {
      "command": "npx",
      "args": ["-y", "yhn-mcp"],
      "env": {
        "YHN_API_KEY": "yhn_..."
      }
    }
  }
}

Cursor

Settings → MCP → New MCP Server, paste the same JSON.

Cline / Continue / other MCP clients

Same JSON shape, drop into the client's MCP config. Anything that speaks stdio MCP works.

Available tools

| Tool | Purpose | |---|---| | whoami | Verify the API key, return plan + email | | create_link | Create a short link (url, optional customSlug, password, expiresAt, OG, UTM, tags) | | list_links | Paginated list with search / folder / tag filter | | get_link | Fetch one link by ID | | update_link | Patch any field (retarget, expire, archive, move folder) | | delete_link | Permanent delete | | get_link_stats | Time series + geo + device + referrer for one link | | bulk_create_links | Create many links in one call (CSV import / migration) | | get_qr_url | Returns a signed-style QR PNG URL for a link | | list_folders / create_folder | Folder management | | list_tags / create_tag | Tag management | | analytics_overview | Account-wide totals + top links | | analytics_geo | Country/city click breakdown | | list_conversion_goals / track_conversion | Server-side conversion events | | list_webhooks / create_webhook | Webhook subscriptions | | list_domains | Custom domains (Pro+) |

More endpoints (A/B test, geo/device routing rules, pixels, marketplace) are exposed via the raw y.hn API; ask if you'd like a tool for them.

Configuration

| env var | default | purpose | |---|---|---| | YHN_API_KEY | required | Your y.hn API key (yhn_...) | | YHN_BASE_URL | https://y.hn/api | Override for self-hosted / staging |

Examples

Once installed, you can prompt naturally:

Shorten https://huggingface.co/blog/agents and put it in folder Reading list.

Bulk-shorten the URLs in /path/to/links.txt, set utm_source=newsletter on all of them, and email me the resulting CSV.

What's my top performing link this week? Pull stats and tell me where the clicks came from.

The agent picks the right tool, calls it, and continues.

Development

npm install
npm run build
node dist/index.js   # smoke test (will exit because YHN_API_KEY missing)

License

MIT