ripper-mcp

A lightweight, local MCP server for Ripper. It exposes everything the in-app assistant can do — contacts, listings, tasks, notes, timeline, and cross-CRM search — to any MCP client (Claude Desktop, Claude Code, Cursor, …), authenticated as your own Ripper account.

It's a thin, generic shell: it knows no individual tool. It reads the tool catalog from the deployed Ripper backend at runtime and dispatches every call through a single gateway. So:

• Tool changes are live. It polls the backend's manifest; when the catalog changes it swaps its tool list and emits notifications/tools/list_changed — no reinstall, no restart.
• The client stays current on its own. Launched via npx ripper-mcp@latest, every start fetches the newest version. A rare backend shellVersion bump just prints an update notice.

The backend half of this (the mcp.* gateway) lives in the private Ripper app. This repo is only the local client.

Quick start

# 1. Log in once (browser SSO — your normal Google sign-in). Caches a personal
#    token at ~/.ripper/credentials.json (chmod 0600).
npx ripper-mcp@latest login

# 2. Check state
npx ripper-mcp@latest status

login starts a loopback listener and opens the /mcp/connect consent page. Sign in, click Approve, and the authorization code is redirected straight back to the CLI on 127.0.0.1 and exchanged for your token (PKCE — see below).

Wire it into a client

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "ripper": {
      "command": "npx",
      "args": ["-y", "ripper-mcp@latest"]
    }
  }
}

Claude Code — .mcp.json (or claude mcp add):

{
  "mcpServers": {
    "ripper": { "command": "npx", "args": ["-y", "ripper-mcp@latest"] }
  }
}

Prefer a global install? npm i -g ripper-mcp then use "command": "ripper-mcp".

How it fits together

Claude Desktop / Cursor  ──stdio──▶  ripper-mcp (local)  ──HTTPS──▶  Ripper backend (Convex)
                                         │                              ├─ mcp.getManifest  (tool catalog + versions)
                                         │                              ├─ mcp.callTool     (runs a tool as you)
                                         └─ ~/.ripper/credentials.json  ├─ mcp.authorize   (browser consent → code)
                                                                        └─ mcp.token       (PKCE exchange → token)

Login uses OAuth 2.0 Authorization Code + PKCE with a loopback redirect (RFC 8252 — the same native-app flow as gh / gcloud): login starts a listener on 127.0.0.1, opens the consent page, and after you approve, the authorization code is redirected to your own loopback and exchanged (with the PKCE verifier that never leaves this machine) for a 90-day access token. Only the token's SHA-256 hash is stored on the backend; no password is ever handled here.

Commands

ripper-mcp            # start the stdio server (default)
ripper-mcp serve      # explicit
ripper-mcp login      # browser-SSO login, cache token
ripper-mcp logout     # clear cached token
ripper-mcp status     # show config + login state

Configuration

Resolution order for every setting: CLI flag → env var → ~/.ripper/credentials.json → default.

Setting	Flag	Env var	Default
Backend URL	--convex-url	RIPPER_CONVEX_URL	reliable-bullfrog-975 (production)
App URL	--app-url	RIPPER_APP_URL	https://rippr.dev (production)
Token	—	RIPPER_MCP_TOKEN	cached after login
Poll period	—	RIPPER_MCP_POLL_MS	60000 (min 10000)

Update controls:

Env var	Effect
RIPPER_MCP_NO_SELFUPDATE=1	Suppress the "newer version available" notice.
RIPPER_MCP_AUTO_UPDATE=1	Also run npm i -g ripper-mcp@latest in the background when behind.

Security notes

• PKCE + loopback means an authorization code is only ever delivered to your 127.0.0.1, and can't be exchanged for a token without the verifier that never leaves this machine — so a phished or intercepted code is useless to anyone else. The listener binds to loopback only and checks the state.
• Tokens expire after 90 days and are revocable. Only their SHA-256 hash is stored server-side; the plaintext is returned to the CLI once and cached at ~/.ripper/credentials.json (chmod 0600).
• Rotate/revoke by running ripper-mcp logout then login again (or revoking the token from the Ripper app). Treat the credentials file like any credential.

Development

npm install
npm run check          # syntax-check all sources
node bin.mjs status

Run against a non-default deployment with --convex-url / RIPPER_CONVEX_URL.

License

MIT