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

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

Configuration

Tools

Links

Analytics

QR & URL helpers

Tags & folders

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.