Skip to main content
Glama
ysalitrynskyi

opn-mcp

by ysalitrynskyi
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

opn-mcp

opn-mcp MCP server

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):

{
  "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:

{
  "mcpServers": {
    "opn": {
      "command": "npx",
      "args": ["-y", "opn-mcp"],
      "env": {
        "OPN_API_KEY": "opn_your_key_here",
        "OPN_BASE_URL": "https://l.your-domain.com"
      }
    }
  }
}

Related MCP server: PicSee Short Link

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

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):

    npm login
npm publish        # prepublishOnly runs the build

  4. Publish to the MCP registry (as GitHub user ysalitrynskyi):

    mcp-publisher validate      # optional, offline check
mcp-publisher login github  # interactive browser OAuth
mcp-publisher publish

Smithery (smithery.yaml) and Glama (glama.json) track the npm/registry release automatically — no separate step.

License

MIT © ysalitrynskyi. Part of the opn.onl project.

Available Tools

2 tools
get_qr_codeB

Get the QR code for a link, optionally branded with a colour, centre logo, and PNG/SVG format.

ParametersJSON Schema
NameRequiredDescriptionDefault
idYesThe link id
logoNoOverlay the brand logo in the centre
colorNoHex foreground colour, e.g. 2f37d8
formatNoImage format (default png)

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It implies read-only retrieval via 'Get', but doesn't explicitly confirm non-destructive behavior, response format, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, 21 words, efficient and front-loaded. However, it could be slightly more structured (e.g., separate required vs optional).

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple 'get' tool, but missing return type (likely image or URL) and any mention of the required 'id' parameter in the description itself.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so baseline is 3. Description adds a summary of optional parameters but no new semantic information beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'QR code for a link', and mentions optional customizations (colour, logo, format). This distinguishes it from sibling tools like shorten_url or list_links.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives, such as checking URL health or getting link stats. It doesn't specify prerequisites or conditions for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.2.0
    • Addedadd_tags_to_link
    • Removeddelete_link
    • Addedget_qr_code
  2. 6 tool updatesv1.2.0
    • Removedcheck_url_health
    • Removedget_link_stats
    • Removedget_qr_code
    • Removedlist_links
    • Removedshorten_url
    • Removedupdate_link
  3. 7 tool updatesv1.1.0
    • First observedcheck_url_health
    • First observeddelete_link
    • First observedget_link_stats
    • First observedget_qr_code
    • First observedlist_links
    • First observedshorten_url
    • First observedupdate_link
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools serve entirely different purposes: one manages tags on links, the other generates QR codes. There is no functional overlap.

Naming Consistency5/5

Both tools follow a clear verb_noun pattern: 'add_tags_to_link' and 'get_qr_code'. The naming is uniform and predictable.

Tool Count3/5

With only two tools, the server feels minimal. While it may cover a narrow use case, the count is borderline for a typical MCP server.

Completeness2/5

The domain appears to be link management, but essential operations like creating, retrieving, or deleting links are missing. This leaves obvious gaps.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • PicSee Short Link

    PicSeeInc
    A
    license
    Not graded
    quality
    A
    maintenance
    Official PicSee MCP server for creating short links. OAuth unlocks link management and click analytics; anonymous shortening is supported.
    MIT
  • INBIO MCP Server by getinbio

    INBIO MCP Serverofficial

    getinbio
    A
    license
    Not graded
    quality
    C
    maintenance
    Official MCP server for INBIO's URL shortener with click analytics and customizable QR codes. Enables link shortening, QR code generation, and link management with optional authentication for advanced features.
    MIT
  • CodeQR Remote MCP Server by codeqr-io

    CodeQR Remote MCP Serverofficial

    codeqr-io
    F
    license
    Not graded
    quality
    B
    maintenance
    Remote MCP server for CodeQR that lets you create and manage short links and QR codes, retrieve analytics, and more via natural language in ChatGPT and other MCP clients.
    -