ysalitrynskyi/opn-mcp

An MCP server for **opn.onl** — the open-source, self-hostable URL shortener. It lets AI assistants (Claude Desktop, Cursor, etc.) shorten links, read analytics, generate QR codes, and manage links in natural language.
Works against the hosted service **or your own self-hosted instance**.
Setup
1. Get an API key
On your opn.onl instance, go to **Settings → API Keys**, create a key, and copy it (it starts with opn_ and is shown once).
2. Add the server to your MCP client
**Claude Desktop** — edit claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%\Claude\ on Windows):
Restart your client. That's it — it talks to the hosted API (https://l.opn.onl) by default.
> Prefer to run from source? Swap the args for the GitHub build — same config:
> "args": ["-y", "github:ysalitrynskyi/opn-mcp"] (it builds on install).
Self-hosted instance
Point OPN_BASE_URL at your own instance's API host:
Configuration
| Env var | Required | Default | Description |
|---------|----------|---------|-------------|
| OPN_API_KEY | ✅ | — | Your API key (opn_…), from Settings → API Keys |
| OPN_BASE_URL | — | https://l.opn.onl | API base URL — set this for a self-hosted instance |
Tools
**Links**
| Tool | Description |
|------|-------------|
| shorten_url | Create a short link — optional alias, title, notes, scheduling (starts_at/expires_at), max_clicks, password, burn-after-reading, folder and tags |
| shorten_urls_bulk | Shorten many URLs at once, optionally into a folder |
| list_links | List your links (limit, offset, search, folder or tag filter) |
| update_link | Update destination, title, notes, scheduling, click limit, folder or protections; clear fields with remove_* flags |
| delete_link | Delete a link |
| clone_link | Duplicate a link under a fresh short code |
| toggle_link_pin | Pin or unpin a link |
| check_alias_available | Check whether a custom alias is free before using it |
**Analytics**
| Tool | Description |
|------|-------------|
| get_link_stats | Per-link analytics (clicks, unique visitors, geo, cities, devices, browsers, OS, referrers); optional days window |
| get_dashboard_stats | Account-wide analytics across all your links |
**QR & URL helpers**
| Tool | Description |
|------|-------------|
| get_qr_code | Get a link's QR image — optional brand colour, centre logo, PNG/SVG |
| check_url_health | Check a destination URL is reachable before shortening |
| build_utm_url | Append UTM campaign parameters to a URL |
| preview_url_metadata | Fetch Open Graph metadata (title, description, image) for a URL |
**Tags & folders**
| Tool | Description |
|------|-------------|
| list_tags / create_tag | List or create tags |
| add_tags_to_link / remove_tags_from_link | Attach or detach tags on a link |
| list_folders / create_folder | List or create folders |
| move_links_to_folder | Move links into a folder |