Skip to main content
Glama
roo-mcp
by dzisner

roo-mcp

npm version node license

MCP server for Roo — the smart-shortlink API. Exposes Roo's link + add-on operations as thin, well-shaped MCP tools an LLM can use directly.

New here? See SETUP.md for a step-by-step install guide (Claude Desktop, Claude Code, Cursor).

Install

Option A — Claude Code plugin (one command; ships MCP + skill together)

claude plugin add https://github.com/roo-bz/roo-mcp.git

Then set your API key once as a user environment variable so the spawned server inherits it:

# Windows PowerShell
[Environment]::SetEnvironmentVariable('ROO_API_KEY', 'your-roo-api-key', 'User')
# macOS / Linux — in ~/.zshrc or ~/.bashrc
export ROO_API_KEY=your-roo-api-key

Restart your terminal + Claude Code. You get both:

  • The 14 roo_* tools (via the MCP server declared in .mcp.json).

  • The roo-shortlinks skill (in skills/roo-shortlinks/) that teaches Claude when to reach for which add-on.

Option B — Manual MCP config (Claude Desktop, Cursor, Continue.dev, other MCP clients)

Add to your MCP client config file:

{
  "mcpServers": {
    "roo": {
      "command": "npx",
      "args": ["-y", "@roo-bz/roo-mcp"],
      "env": { "ROO_API_KEY": "your-roo-api-key" }
    }
  }
}

See SETUP.md for the exact config file path per client. Get an API key from https://roo.bz — see your account API settings.

Related MCP server: linkbit-mcp

Local development

npm install
cp .env.example .env    # then paste ROO_API_KEY into .env
npm run build
node scripts/smoke.mjs  # spawns the built server, calls tools/list + roo_whoami

Key resolution: at startup the server looks for ROO_API_KEY in this order:

  1. process.env.ROO_API_KEY — how MCP clients normally inject it via their mcpServers.env config.

  2. .env in the package root (../ from the built script) — convenience for local dev, especially when a desktop MCP client (Claude Desktop, etc.) doesn't reliably pass user env vars through to spawned processes.

If neither is present, the server exits with a clear error.

Tools (implemented / planned)

  • roo_whoami — verify key + compact account summary.

  • roo_list_shortlinks, roo_create_shortlink, roo_get_shortlink, roo_update_shortlink — CRUD.

  • roo_make_permanent, roo_update_permanent_settings — permanence.

  • roo_get_qr_code — retrieve QR (base64 data URI or write to file).

  • roo_set_scheduled_redirect, roo_set_click_count_redirect, roo_set_webhook, roo_set_preview_link, roo_set_qr_addon — the five add-ons.

Design & spec

  • DESIGN.md — build brief (tool catalog, architecture, error handling).

  • skills/roo-shortlinks/SKILL.md — companion Claude skill (judgment layer), bundled with the plugin.

  • SPEC-NOTES.md — spec-vs-reality findings from live probes.

  • roo-openapi.json — the extracted Swagger 2.0 spec.

Available Tools

14 tools
roo_get_qr_codeRoo — get shortlink QR imageA

Fetch the QR image for a shortlink. Requires the qrCode add-on to already be configured on the shortlink (via roo_set_qr_addon) — otherwise Roo returns a qr_not_enabled error. By default returns the image inline as an MCP image content block; pass save_to (absolute path) to write the bytes to a file instead.

Inputs: id (required), save_to.

roo_list_custom_domainsRoo — list custom domainsA

List every custom domain attached to the account, with each one's status and verification details. Authoritative — this is the same data the Roo web app uses. Distinct from the domain a particular SHORTLINK is on (a shortlink can be on roo.ws or roo.bz — Roo-owned defaults — without any custom domain being attached).

Inputs: status_filter.

roo_make_permanentRoo — make shortlink permanentA

Mark a shortlink as permanent — it stops participating in the plan's auto-expiry (Hop = 90 days). Counts against the account's permanent-shortlink limit. To un-make a link permanent, use roo_update_permanent_settings with { permanent: false }.

Inputs: id (required).

roo_set_click_count_redirectRoo — set click-count redirectA

Click-count redirect: attach or replace cumulative thresholds on the shortlink. After the shortlink accumulates click_count clicks, the destination switches to url and stays until the next threshold. Order thresholds by increasing click_count; the tool re-sorts.

Inputs: id (required), thresholds (required).

roo_set_qr_addonRoo — configure QR add-onA

Configure and enable the QR code add-on on a shortlink. Roo requires all 6 fields; the tool defaults them all. After this succeeds, use roo_get_qr_code to fetch the rendered image.

Inputs: id (required), logo, scale, style, +3 more.

roo_set_scheduled_redirectRoo — set scheduled redirectA

Time-based redirect: attach or replace waypoints on the shortlink. Each waypoint is a { url, at } pair — at time T the redirect switches to url and stays until the next waypoint. Before the first waypoint the shortlink falls through to its base url. Roo has no timezone or per-waypoint end field.

Inputs: id (required), waypoints (required).

roo_set_webhookRoo — set webhookA

Fire an HTTP request to endpoint on every click. Roo requires 8 fields; this tool defaults 7 of them — you only need to provide the endpoint. The webhook does NOT change where the shortlink redirects to; the destination is unchanged.

Inputs: id (required), endpoint (required), body, name, +5 more.

roo_update_permanent_settingsRoo — update permanent settingsA

Update permanent-mode settings on a shortlink. Today the only verified field is permanent (true/false) — additional fields may be accepted by the endpoint in the future; only fields you pass are sent.

Inputs: id (required), permanent.

roo_whoamiRoo — who am IA

Verify the Roo API key and return a compact account summary (email, plan, limits, subscription dates). Use to check that Roo access is working before other operations.

Inputs: no named parameters.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 14 tools

    Disambiguation4/5

    The tool set is largely distinct: shortlink CRUD, previews, QR codes, webhooks, and redirect rules each map to separate responsibilities. The main overlap is between roo_make_permanent and roo_update_permanent_settings, since both can enable permanent mode and the latter is also used to disable it.

    Naming Consistency4/5

    Most tools follow a consistent roo_verb_object snake_case pattern such as list_shortlinks, create_shortlink, get_shortlink, and set_webhook. Minor outliers like roo_whoami and roo_make_permanent break the object-noun pattern, but overall the naming is predictable.

    Tool Count4/5

    14 tools is a reasonable size for a shortlink platform covering core CRUD, custom domains, QR codes, redirect rules, webhooks, and preview settings. The count is slightly padded by redundant permanent-link control, but no tool feels wildly out of place.

    Completeness3/5

    Core operations are well covered for shortlink creation, retrieval, updating, and listing, plus several add-on features. However, there is no delete/remove shortlink tool, and add-ons like webhooks, QR codes, or redirect rules cannot be explicitly disabled — only replaced.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables creation and management of short links with custom slugs, QR repointing, and cookieless analytics from any MCP client.
      7 npm
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables users to shorten links, bulk-create URLs, generate QR codes, and retrieve click analytics through MCP clients such as Claude, ChatGPT, Cursor, and n8n.
      9
      40 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to create, update, organize, and delete short links; render styled QR codes; route visitors by device or country; and read click and scan statistics. Agents can also manage groups and custom domains while changing destinations without breaking printed QR codes or shared short URLs.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables any MCP client to create, manage and measure short links on branded domains, including batch creation, per-day cookie-less click analytics, campaign roll-ups, UTM link building and QR code generation. Connects through a single hosted endpoint with OAuth sign-in or scoped tokens, so assistants can work within chosen workspaces without installing anything.
      MIT