io.github.ysalitrynskyi/opn-mcp
MCP server for opn.onl: shorten links, analytics, branded QR codes, and link management.
Open source Open in the app JSON README (API)
About
MCP server for opn.onl: shorten links, analytics, branded QR codes, and link management.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- ysalitrynskyi
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.2.0
- Stars
- 2
- Last push
- 2026-07-17T14:13:30Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 04:01:42
- Updated
- 2026-08-29 04:01:42
- Origin id
io.github.ysalitrynskyi/opn-mcp
README
# opn-mcp
[](https://glama.ai/mcp/servers/ysalitrynskyi/opn-mcp)
An [MCP](https://modelcontextprotocol.io) server for **[opn.onl](https://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):
```json
{
"mcpServers": {
"opn": {
"command": "npx",
"args": ["-y", "opn-mcp"],
"env": {
"OPN_API_KEY": "opn_your_key_here"
}
}
}
}
```
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:
```json
{
"mcpServers": {
"opn": {
"command": "npx",
"args": ["-y", "opn-mcp"],
"env": {
"OPN_API_KEY": "opn_your_key_here",
"OPN_BASE_URL": "https://l.your-domain.com"
}
}
}
}
```
## 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 |
## Example prompts
- "Shorten https://example.com/very/long/url and call it launch-2026"
- "Shorten these five URLs into a new folder called Q3 Campaign"
- "How many clicks did link 42 get in the last 30 days, and from which countries?"
- "Give me a branded SVG QR code for link 42"
- "Tag my last 10 links as 'newsletter' and show my dashboard stats"
- "Build a UTM link for https://example.com — source newsletter, medium email"
## Development
```bash
npm install
npm run build # tsc → dist/
npm test # vitest
OPN_API_KEY=opn_… npm run dev # run from source (stdio)
```
## Releasing
All three registries are owned by **`ysalitrynskyi`** (npm user, GitHub user, and
the `io.github.ysalitrynskyi` MCP-registry namespace), so publishing must be done
while signed in as that account.
1. Bump the version in **three** places and keep them identical:
`package.json`, `server.json` (top-level **and** the `packages[0].version`),
and `SERVER_VERSION` in `src/server.ts`.
2. Land it: commit to `main` and push. CI (`.github/workflows/ci.yml`) runs
`build` + `test` — it does **not** publish.
3. Publish to npm (as npm user `ysalitrynskyi`):
```bash
npm login
npm publish # prepublishOnly runs the build
```
4. Publish to the MCP registry (as GitHub user `ysalitrynskyi`):
```bash
mcp-publisher validate # optional, offline check
mcp-publisher login github # interactive browser OAuth
mcp-publisher publish
```
[Smithery](https://smithery.ai) (`smithery.yaml`) and [Glama](https://glama.ai)
(`glama.json`) track the npm/registry release automatically — no separate step.
## License
MIT © ysalitrynskyi. Part of the [opn.onl](https://github.com/ysalitrynskyi/opn.onl) project.