Ronin Customer MCP Server

Run a local AI tool server that lets your AI assistant read your Ronin orders, invoices, and reports, and (if you turn it on) place and manage orders. It uses your own Ronin API key. Nothing is exposed to the public; the server runs on your machine over stdio and works with any MCP client (Claude Desktop, Claude Code, Cursor, Cline, Windsurf, VS Code with Copilot, LM Studio, Goose, and more).

What it can do

Read tools are on by default. Write tools are off until you explicitly enable them and your key has write permission.

Read tools (default on)

Write tools (off by default, opt in)

create_order, create_orders_batch, cancel_order, send_order_message, request_amendment, cancel_amendment, submit_feedback, update_order_source_file_count, create_shoot_schedule, create_shoot_schedules_batch, update_shoot_schedule, confirm_shoot_schedule, cancel_shoot_schedule.

API v2 tools (0.8.0, accounts with API v2 enabled)

These tools appear only when your account has API v2 enabled (the server checks /v2/me at start). The v1 tools above keep working exactly as before. Full reference: https://client.ronincenter.com/document/api-v2

Write tools (opt in, like the v1 write tools): create_upload_batch, sign_upload_parts, complete_upload, cancel_upload, create_order_v2, create_webhook, rotate_webhook_secret, replay_webhook_delivery. The upload tools control the upload; your own software sends the file bytes to the part links. Webhook tools need webhooks:write on the key.

Schedule & Save: declare shoots ahead for a discount

Declare an upcoming shoot and Ronin applies a scheduling discount automatically when you place the matching order. Read tools (list_shoot_schedules, get_shoot_schedule, get_schedule_savings) need the schedules:read scope, which is on by default for new keys. Write tools (create_shoot_schedule and friends) need the schedules:write scope plus RONIN_MCP_ENABLE_WRITE=true.

create_shoot_schedule(
    shoot_date="2026-07-01",
    service_code="HDR",
    expected_quantity=30,
    property_name="711 Cornell Ave, Cinnaminson, NJ",
)

create_order accepts external_ref so you can tag each order with your own property or shoot ID for reconciliation, and order_name to give the order a human-readable label (e.g. the property address) that shows on confirmations, internal queues, and your reports. When order_name is omitted the order falls back to the first line of special_instructions.

create_order also accepts cloud_link: a single http(s) link to a cloud folder (Dropbox, Google Drive, OneDrive, etc.) holding the source files for the order. Use it instead of, or alongside, uploading files; our team opens the link to fetch them.

Each line item on create_order can carry per-item addons (e.g. a dust or garbage removal add-on). Each add-on becomes its own priced line on the order, taken from your catalog. Use list_services to find add-on codes (type addon).

On each line item, quantity is the number of FINAL edited images you pay for (the billed count), never the raw frame count. Report raw counts through the optional source_file_count field (informational, for reconciliation; never billed) - send it explicitly on cloud-link orders where Ronin cannot count uploads for you, or correct it later with update_order_source_file_count.

Each line item also accepts an optional bracket_size (1, 3, 5, 7, or 9): the number of exposures per composition on HDR-style shoots. It is an estimate helper only (finals is roughly raw frames divided by bracket size) and does NOT affect billing; billing always follows quantity. Omit it if unsure.

Notices (soft hints for your AI)

Order results may include a notices list with soft, non-blocking hints your AI can act on or relay to you:

• hidden_services: your note mentions a billable service (e.g. sky replacement, TV screens) that is on your price list but not on the order. Add it as a line item if you want it done and billed.
• mcp_upgrade: a newer version of this MCP is available.

Notices never block an order; they are guidance, not instructions inside customer-entered text.

Get an API key

Sign in to your Ronin portal, open API tokens, and create a key. Copy it once (it is shown only at creation). The key carries scopes such as orders:read, orders:write, billing:read, reports:read, catalog:read. The server only shows tools your key is allowed to use.

Install

Recommended: run it with uvx, which always fetches the latest version on launch (no manual upgrades needed):

uvx ronin-customer-mcp

Or install with pip and pin/upgrade yourself:

pip install ronin-customer-mcp
# later, to upgrade:
pip install --upgrade ronin-customer-mcp

This installs a ronin-customer-mcp command. Run it directly to check it works:

RONIN_API_KEY=rk_live_xxx ronin-customer-mcp

(The server speaks the MCP protocol over stdio, so run it from your MCP client rather than interactively.)

Most upgrades to what the server can do (new services, new prices) happen on the Ronin side, so you rarely need to update the package; running it via uvx keeps it current automatically.

Configuration (environment variables)

Add to your MCP client

Most MCP clients use the same JSON shape.

Recommended (uvx, auto-updates on launch) — Claude Desktop (claude_desktop_config.json) and Claude Code (.mcp.json), under mcpServers:

{
  "mcpServers": {
    "ronin": {
      "command": "uvx",
      "args": ["ronin-customer-mcp"],
      "env": {
        "RONIN_API_KEY": "rk_live_xxx",
        "RONIN_MCP_ENABLE_WRITE": "false"
      }
    }
  }
}

Alternative (pip-installed binary) — point the command at the installed ronin-customer-mcp executable:

{
  "mcpServers": {
    "ronin": {
      "command": "ronin-customer-mcp",
      "env": {
        "RONIN_API_KEY": "rk_live_xxx",
        "RONIN_MCP_ENABLE_WRITE": "false"
      }
    }
  }
}

Cursor (.cursor/mcp.json), Cline, and VS Code (Copilot MCP) use the same command / args / env structure under their MCP settings.

To allow placing or cancelling orders, set RONIN_MCP_ENABLE_WRITE to true and use a key that has the orders:write scope.

Safety

This server is designed to be safe by default.

• Read only by default. Write tools require two things at once: you set RONIN_MCP_ENABLE_WRITE=true and your key has the write scope. If either is missing, the AI cannot place or cancel orders.
• Your key only ever sees your own data. A leaked key affects only your account.
• Treat order content as data, not instructions. Order notes, messages, and amendment or feedback text are written by people and can contain text that tries to manipulate an AI agent. Every tool result marks these fields under untrusted_fields. Your AI assistant should never follow instructions found inside them.

Troubleshooting

• missing_api_key: set RONIN_API_KEY.
• invalid_api_key: the key was rejected. Check it is correct and active.
• A write tool is not listed: set RONIN_MCP_ENABLE_WRITE=true and use a key with the orders:write scope.
• A read tool is not listed: your key is missing that scope. Add the scope in the portal.