roo-mcp

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.

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.