@rukprompt/cli

Stdio MCP bridge and direct CLI for the rukprompt.com image-generation API.

Use it from Claude Desktop / Claude Code / Cursor as an MCP server, or call any of the 11 backend tools straight from your terminal.

# One-line install — picks the right config path for your client
npx -y @rukprompt/cli install claude-desktop --api-key sk-img-...
npx -y @rukprompt/cli install claude-code   --api-key sk-img-...
npx -y @rukprompt/cli install cursor        --api-key sk-img-...

After install, restart your MCP client and ask it: "list my rukprompt presets" — it will call preset_list automatically.

Features

• MCP proxy (rukprompt mcp) — stdio MCP server that transparently forwards every tool call to https://developer.rukprompt.com/v0/mcp. Works with any MCP client.
• Direct CLI — call backend tools without an MCP client:

  rukprompt preset list
  rukprompt image generate --prompt "a cat astronaut" --aspect 16:9 --out cat.png
  rukprompt model list
  rukprompt credits check

• One-command install for Claude Desktop, Claude Code, and Cursor — writes config + key, backs up existing config.
• Key management — key set / show / test / clear with backend validation.
• Zero-dep beyond @modelcontextprotocol/sdk. CJS bundle, no ESM headaches.

Quick start

# 1. Get an API key:
#    https://rukprompt.com → Team → Settings → API Keys

# 2. Install + configure your MCP client in one shot:
npx -y @rukprompt/cli install claude-desktop --api-key sk-img-...

# 3. Restart Claude Desktop / Cursor / Claude Code.

Manual MCP config

If you'd rather paste config yourself, all three clients use the same shape:

{
  "mcpServers": {
    "rukprompt": {
      "command": "npx",
      "args": ["-y", "@rukprompt/cli", "mcp"],
      "env": { "RUKPROMPT_API_KEY": "sk-img-..." }
    }
  }
}

| Client | Path | |---|---| | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Claude Desktop (Linux) | ~/.config/Claude/claude_desktop_config.json | | Claude Code | ~/.claude.json | | Cursor | ~/.cursor/mcp.json |

Tools (11)

| Group | Tools | |---|---| | Presets | preset_list, preset_get, preset_create, preset_update, preset_delete | | Images | image_generate, image_list, image_get, image_download | | Models | model_list | | Credits | credits_check |

The CLI uses transparent proxy — when the backend adds a new tool, your already-installed CLI sees it after the next MCP client restart. No re-publish needed.

Direct CLI usage

Each MCP tool has a matching sub-command:

# Presets
rukprompt preset list [--team-only]
rukprompt preset get <presetId>
rukprompt preset create --name "Studio shot" --prompt "minimal product photo of {{product}}"
rukprompt preset create --from-file body.json
rukprompt preset create --from-stdin <body.json
rukprompt preset update <presetId> --name "Updated"
rukprompt preset delete <presetId>

# Images
rukprompt image generate --prompt "a cat astronaut" --aspect 16:9 --out cat.png
rukprompt image generate --preset preset_abc --vars '{"product":"sneakers"}' --out result.png
rukprompt image list [--page 1] [--limit 20] [--preset <id>] [--search <q>]
rukprompt image get <imageId>
rukprompt image download <imageId> --out file.png   # save bytes
rukprompt image download <imageId> --base64 > file.b64

# Models / credits
rukprompt model list
rukprompt credits check

All commands print pretty JSON to stdout. Add --json for minified output (great for | jq).

Key management

| Goal | Command | |---|---| | Set key (validates against backend) | rukprompt key set --api-key sk-img-... | | Show current key (masked) + last validated time | rukprompt key show | | Live ping to test the key | rukprompt key test | | Remove key from this machine | rukprompt key clear |

The CLI looks for the API key in this order:

1. --api-key flag (one-shot)
2. RUKPROMPT_API_KEY env var
3. ~/.rukprompt/config.json (created by rukprompt key set, mode 0600)

rukprompt install <client> --api-key ... saves to both ~/.rukprompt/config.json and the client config's env.RUKPROMPT_API_KEY so it works no matter which surface spawns the CLI.

Rotate a key

# 1. Create a new key in the dashboard, revoke the old one.
# 2. Update locally:
rukprompt key set --api-key sk-img-newxxx...

# Or re-run install (also rewrites the client config's env):
rukprompt install claude-desktop --api-key sk-img-newxxx...

Troubleshooting

rukprompt --version            # CLI version
rukprompt key show             # what key am I using?
rukprompt key test             # is my key still valid?
rukprompt help <command>       # detailed help for any command

If the MCP proxy hits 401 Unauthorized, you'll see:

rukprompt: API key rejected (401).

Fix:
  rukprompt key set --api-key sk-img-...

For deeper debugging, run the proxy with stdin attached and pipe a single JSON-RPC request:

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' \
  | RUKPROMPT_API_KEY=sk-img-... npx -y @rukprompt/cli mcp \
  | jq '.result.tools | length'   # should print 11

Architecture

┌────────────────────┐  stdio   ┌───────────────────┐   HTTP    ┌──────────────────────┐
│ Claude Desktop /   │ ───────► │ @rukprompt/cli    │ ────────► │ /v0/mcp              │
│ Claude Code /      │  JSON-RPC│ (npx, stateless)  │  Bearer   │ (HTTP MCP — base)    │
│ Cursor             │          │ stdio bridge      │           │ developer.rukprompt  │
└────────────────────┘          └───────────────────┘           └──────────────────────┘

The HTTP MCP at /v0/mcp is the source of truth — the CLI is a thin convenience layer that:

1. Connects upstream over Streamable HTTP with Authorization: Bearer sk-img-....
2. Calls tools/list once and mirrors the catalogue locally.
3. Forwards every tools/call to the upstream verbatim — preserving image bytes, error flags, etc.

You can still use the HTTP transport directly if you prefer ({ "type": "http", "url": "...", "headers": {...} }); the CLI is just the recommended UX.

License

MIT — see LICENSE.