ronin-customer-mcp 0.7.0

Run your Ronin Editing account from any AI assistant. A local MCP server that lets Claude, Cursor, Cline, VS Code and other MCP clients read your orders, invoices and reports, and (opt in) place and manage orders, using your own Ronin API key.

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)

Tool	What it does
list_orders	List your orders, optionally filtered by status
get_order	Full detail for one order
get_order_delivery	Delivery info and download links for an order
list_order_messages	Messages on an order thread
list_order_amendments	Amendment requests on an order
list_invoices / get_invoice	Your invoices
get_cost_summary	Cost report by day for a date range
get_orders_report	Per-order detail report for a date range
get_monthly_statement	Total orders and revenue for a month
get_invoices_report	Invoices report by status
list_services / get_service	The service catalog
preview_pricing	Price a cart of services without placing an order
list_shoot_schedules / get_shoot_schedule	Your declared upcoming shoots (Schedule & Save)
get_schedule_savings	The current scheduling discount (base rate plus any promotion)
whoami / get_usage	Account, key, and recent usage

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.

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)

Variable	Required	Default	Meaning
RONIN_API_KEY	yes	none	Your Ronin API key
RONIN_API_BASE_URL	no	https://api.ronincenter.com	API base URL
RONIN_MCP_ENABLE_WRITE	no	false	Set true to expose write tools

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.