This is the full developer documentation for Muro # Muro for developers > Real paint colours from real brands, cross-brand equivalents and room photos painted in any colour. For AI agents over MCP, in your terminal, or paid per call in USDC. ## Connect in one line [Section titled “Connect in one line”](#connect-in-one-line) ```text https://mcp.usemuro.com/mcp ``` Add this URL as a remote MCP server in Claude, ChatGPT, Cursor or any MCP client. Colour search is free and needs no sign-in. See the [Quickstart](/start/quickstart/) for each client. Search real paint colours Find colours by name or code across 35 manufacturer catalogues, about 51,000 colours. Free. Cross-brand equivalents Get the closest match to any colour in other brands, ranked by CIEDE2000 ΔE. Free. Paint a room photo Send a photo and up to 12 colours; get each one painted on the walls, facade or roof. Relight a room See a painted interior by day, in the evening or at night, with lamps on or off. ## Ways in [Section titled “Ways in”](#ways-in) [MCP server](/mcp/overview/)8 tools for agents: search, equivalents, painting, relighting. [CLI](/cli/)npx usemuro: the same tools in your terminal and scripts. [API keys and OAuth](/auth/api-keys/)Pay for painting with Muro credits from your account. [x402](/x402/)No account: pay per call in USDC on Base. ## For LLMs [Section titled “For LLMs”](#for-llms) This documentation is also available as plain text for agents: [`/llms.txt`](/llms.txt), [`/llms-full.txt`](/llms-full.txt) and [`/llms-small.txt`](/llms-small.txt). # API keys > Create a Muro API key, send it as a Bearer header from Claude Code, Cursor or VS Code, and revoke it. A Muro API key unlocks the painting tools (`visualize_room`, `get_visualization`, `relight_room`, `get_credits`). The colour tools stay free with or without a key. Painting spends the **credits of the Muro account that owns the key**, the same credits as the app. There are no free trials. If you have no account and want to pay per call instead, use [x402](/x402/). ## Create a key [Section titled “Create a key”](#create-a-key) 1. Sign in at [app.usemuro.com](https://app.usemuro.com). 2. Open Settings and create a key under **API keys**. 3. Copy it right away. The key is shown once. A key looks like `muro_sk_` followed by 43 characters (letters, digits, `-` and `_`). Treat it like a password: it spends your money. Do not commit it to a repository or paste it into a shared chat. ## Send it as a header [Section titled “Send it as a header”](#send-it-as-a-header) Send the key on every request to `https://mcp.usemuro.com/mcp`: ```http Authorization: Bearer muro_sk_… ``` Only tokens that start with `muro_sk_` are accepted. Any other `Authorization` value is ignored and the call is treated as keyless. ### Claude Code [Section titled “Claude Code”](#claude-code) ```bash claude mcp add --transport http muro-colors https://mcp.usemuro.com/mcp --header "Authorization: Bearer muro_sk_…" ``` ### Cursor [Section titled “Cursor”](#cursor) In `~/.cursor/mcp.json`: ```json { "mcpServers": { "muro-colors": { "url": "https://mcp.usemuro.com/mcp", "headers": { "Authorization": "Bearer muro_sk_…" } } } } ``` ### VS Code (Copilot agent mode) [Section titled “VS Code (Copilot agent mode)”](#vs-code-copilot-agent-mode) In `.vscode/mcp.json`: ```json { "servers": { "muro-colors": { "type": "http", "url": "https://mcp.usemuro.com/mcp", "headers": { "Authorization": "Bearer muro_sk_…" } } } } ``` ### claude.ai and ChatGPT [Section titled “claude.ai and ChatGPT”](#claudeai-and-chatgpt) These connectors cannot send a header. Use [Sign in with Muro](/auth/oauth/) at `https://mcp.usemuro.com/account/mcp`. It creates and manages a key for you. ### CLI [Section titled “CLI”](#cli) ```bash muro login # paste the key once ``` or set `MURO_API_KEY`. See the [CLI guide](/cli/). ## Check it works [Section titled “Check it works”](#check-it-works) Ask the assistant to run `get_credits`. It returns your balance and plan, for example “120 credits on the pro plan” (the numbers are yours). If the key is wrong, you get the message listed under [Errors](/reference/errors/). ## Revoke a key [Section titled “Revoke a key”](#revoke-a-key) Open app.usemuro.com → Settings → API keys and revoke it. The next call with that key is rejected. Revoking also disconnects any assistant that [signed in with Muro](/auth/oauth/) under that key. ## Limits for keyed calls [Section titled “Limits for keyed calls”](#limits-for-keyed-calls) Any request that carries an `Authorization` header is limited to **60 requests per 60 seconds per client IP**, a stricter bucket than the keyless 600 per 60 seconds. Above it the server answers HTTP 429 with `Retry-After: 60`. The limit is enforced per Cloudflare data centre, so treat it as approximate. Details are on [Pricing and limits](/reference/pricing-limits/). A keyed call to a free colour tool counts against the 60 bucket too. If you only need colour data, leave the header off. # Sign in with Muro (OAuth) > How claude.ai and ChatGPT connect to your Muro account without an API key, what you see, and how to disconnect. claude.ai and ChatGPT connectors cannot send an `Authorization` header, so they cannot use an [API key](/auth/api-keys/). For them the server has a second address that signs you in with your Muro account: ```text https://mcp.usemuro.com/account/mcp ``` It exposes the same eight tools as `/mcp`. Painting spends the credits of the account you sign in with. ## What you see [Section titled “What you see”](#what-you-see) 1. In your assistant, add a custom connector with the URL above. In claude.ai: Settings → Connectors → *Add custom connector*, authentication left empty. In ChatGPT: Settings → Apps & Connectors → Advanced → Developer mode → *Create*, with OAuth. 2. A Muro page asks “Connect *assistant name* to your Muro account?”. It says who published the app and where access goes, and lists what the assistant may do: * paint your room photos in the colours you ask for, using your Muro credits * see your credit balance 3. **Continue to Muro** takes you to app.usemuro.com. Sign in if you are not signed in, and confirm again. 4. You are sent back to the assistant, now connected. **Cancel** at either step connects nothing. If the page says the link expired or was already used, go back to the assistant and start connecting again. ## Where the connection appears [Section titled “Where the connection appears”](#where-the-connection-appears) Connecting creates an API key for that assistant. It is listed in app.usemuro.com → Settings → API keys under the assistant’s name. ## Disconnect [Section titled “Disconnect”](#disconnect) Revoke that key in Settings → API keys. The next call from the assistant is rejected (“key rejected”), and you can remove the connector in the assistant too. ## How it works (for developers) [Section titled “How it works (for developers)”](#how-it-works-for-developers) The Worker at `mcp.usemuro.com` is the OAuth 2.1 authorization server, built on `@cloudflare/workers-oauth-provider`. The client never holds your Muro key, only a token issued by this Worker. 1. The client calls `/account/mcp`, gets a `401`, discovers the authorization server from the resource metadata, and registers itself at `/register` (or presents a Client ID Metadata Document). 2. `/authorize` shows the consent page. Continue hands the browser to `app.usemuro.com/connect`, with `state`, `client` and `client_name`. 3. The Muro app signs you in, asks again, creates a `muro_sk_…` key for that client, and POSTs `state` and `key` (or `error`) as a form to `/oauth/callback`. The key never appears in a URL. 4. The callback checks the browser-bound state and verifies the key against the Muro API. It stores the key encrypted inside the grant. The client receives an opaque token from `/oauth/token`. | Item | Value | | --------------------- | ------------------------------------------- | | Resource | `https://mcp.usemuro.com/account/mcp` | | Scope | `muro` | | Registration | `/register`, or Client ID Metadata Document | | Authorization / token | `/authorize`, `/oauth/token` | `/account/mcp`, `/register`, `/authorize` and `/oauth/*` share the keyed rate limit: 60 requests per 60 seconds per client IP. See [Pricing and limits](/reference/pricing-limits/). Clients that can send headers (Claude Code, Cursor, VS Code, scripts) should use an [API key](/auth/api-keys/) at `/mcp` instead. For the server’s discovery document see `https://mcp.usemuro.com/.well-known/mcp.json`. # CLI > The usemuro command line tool. Search paint colours, find cross-brand equivalents and paint a photo from your terminal. `usemuro` brings the Muro catalogue and room painting to your terminal. It talks to the same server as the [MCP tools](/mcp/overview/). Colour lookups are free. Painting uses a Muro [API key](/auth/api-keys/) and your plan’s credits. Source: [github.com/mszyma/muro-cli](https://github.com/mszyma/muro-cli). Requires **Node 20 or newer**. No dependencies. ## Install [Section titled “Install”](#install) Run without installing: ```bash npx usemuro colors search "agreeable gray" ``` Or install globally. The command is then `muro`: ```bash npm install -g usemuro muro colors search "agreeable gray" ``` ## Free colour commands [Section titled “Free colour commands”](#free-colour-commands) No key needed. ```bash muro colors search "agreeable gray" ``` ```text Sherwin-Williams Agreeable Gray (SW 7029) #D1CBC1 https://usemuro.com/en/colors/sherwin_williams/agreeable-gray ``` ```bash muro colors get "Farrow & Ball" "Hague Blue" ``` ```text Farrow & Ball Hague Blue (30) #3D4E57 LRV 29.4 https://usemuro.com/en/colors/farrow_ball/hague-blue ``` ```bash muro colors equivalents "Farrow & Ball" "Hague Blue" --country PL --limit 4 ``` ```text Source: Farrow & Ball Hague Blue (30) #3D4E57 ΔE 0.49 Śnieżka S 7020-b10g (S 7020-B10G) #3D4D56 — practically identical ΔE 1.35 Dulux (PL) S0.16.22 (1384825) #394A53 — very close ΔE 2.33 Tikkurila M438 #435055 — close ΔE 2.35 Flügger 4468 (Flügger Pro 5 - Flügger 900 624) #3D4951 — close ``` `--country PL` puts brands sold in that market first. See [Colour data](/reference/colour-data/) for what ΔE means. ## Commands [Section titled “Commands”](#commands) | Command | What it does | | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `muro colors search [--brand B] [--limit N]` | Search by name or code (free) | | `muro colors get ` | Exact lookup (free) | | `muro colors equivalents ` or `--hex #RRGGBB` `[--country PL] [--limit N]` | Closest colours in other brands, CIEDE2000 (free) | | `muro brands [--country PL]` | Brands, optionally by market (free) | | `muro login [key]` | Save your API key | | `muro logout` | Remove the saved key | | `muro credits` | Show balance and plan | | `muro visualize -c …` | Paint 1 to 12 colours. Options: `--surface interior\|facade\|roof`, `--quality standard\|hd\|ultra`, `--ceiling`, `--country PL`, `--out DIR`, `--yes` | | `muro relight --time day\|evening\|night` | The same result in another light, 1 credit. Options: `--lamps`, `--out DIR` | `colors` also answers to `colours`, and `visualize` to `visualise` and `paint`. Run `muro --help` for the built-in reference and `muro --version` for the version. ## Colour syntax [Section titled “Colour syntax”](#colour-syntax) The `-c` option (repeatable, also `--color` and `--colour`) takes any of: | Form | Example | | -------------- | ---------------------------- | | Hex | `#3D4E57` | | Brand and name | `"Farrow & Ball:Hague Blue"` | | Brand and code | `"Sherwin-Williams:SW 7029"` | | RAL code | `"RAL 9005"` | Give each colour once: a duplicate is refused because every colour is charged. ## Log in [Section titled “Log in”](#log-in) Create a key at app.usemuro.com → Settings → API keys (see [API keys](/auth/api-keys/)), then: ```bash muro login # paste the key when asked muro login muro_sk_… # or pass it as an argument ``` The key is checked against your account and saved to `~/.config/muro/config.json` (readable only by you). Set `MURO_API_KEY` to use a key without saving it, for example in CI. The environment variable wins over the saved file. ## Paint a photo [Section titled “Paint a photo”](#paint-a-photo) ```bash muro visualize living-room.jpg \ -c "Farrow & Ball:Hague Blue" -c "RAL 9005" \ --country PL --out ./paint ``` ```text 1. Farrow & Ball Hague Blue (30) #3D4E57 [c1] → paint/01-farrow-ball-hague-blue.jpg Buy: Śnieżka S 7020-b10g ΔE 0.49 · Dulux (PL) S0.16.22 (1384825) ΔE 1.35 · Tikkurila M438 ΔE 2.33 · Flügger 4468 ΔE 2.35 2. RAL Colors Jet black (RAL 9005) #0E0E10 [c2] → paint/02-ral-colors-jet-black.jpg … Project: https://app.usemuro.com/wynik/… Cost: 2 credits. ``` Each result is saved at full resolution (default folder `muro-out`) with the paint’s brand, name and code, plus the closest paints to buy from other brands. Before spending credits, `visualize` shows the cost and asks `[y/N]`. Pass `--yes` (or `-y`) to skip the question. `--yes` is **required** when the command is not run in a terminal, for example in a script. The photo argument is a file path or an `https://` link. ### Photo formats [Section titled “Photo formats”](#photo-formats) * JPEG, PNG or WebP, up to 12 MB. * **HEIC/HEIF** from an iPhone is converted to JPEG automatically **on macOS** (using the built-in `sips`). On other systems, save it as JPEG first. * 1 to 12 colours per call, each a separate image. * Up to 100 photo uploads a day per account. ### Quality and cost [Section titled “Quality and cost”](#quality-and-cost) `standard` (about 1K) costs 1 credit per colour on any plan. `hd` (about 2K) costs 2 from Pro. `ultra` (about 4K) costs 3 from Premium. See [Pricing and limits](/reference/pricing-limits/). ## Relight [Section titled “Relight”](#relight) Show a painted interior by day, at evening or at night. Use the project id and colour key (`c1`, `c2`, …) from the `visualize` output: ```bash muro relight c1 --time evening ``` It costs 1 credit and saves, for example, `muro-out/c1-evening.jpg`. Add `--lamps` for lamps on. It asks for confirmation in a terminal; `--yes` skips it. ## JSON output [Section titled “JSON output”](#json-output) Every command takes `--json` for scripts and agents: ```bash muro colors search "SW 7029" --json ``` ```json { "query": "SW 7029", "count": 1, "colors": [ { "brand": "Sherwin-Williams", "brand_id": "sherwin_williams", "name": "Agreeable Gray", "hex": "#D1CBC1", "lrv": 79.8, "category": "neutral", "collection": "Sherwin-Williams-all", "code": "SW 7029", "url": "https://usemuro.com/en/colors/sherwin_williams/agreeable-gray" } ], "see_on_your_wall": "Preview it on a photo of your own room with Muro (iPhone, iPad and web): https://app.usemuro.com · App Store: https://apps.apple.com/app/id6757682733", "data_source": "Muro paint colour database (usemuro.com), compiled from manufacturers’ published colour catalogues." } ``` With `--json`, progress messages are not printed. ## Errors [Section titled “Errors”](#errors) The CLI prints `muro: ` and exits non-zero. Common messages: * `This needs a Muro API key. Create one at https://app.usemuro.com/ustawienia (Settings → API keys), then run: muro login` * `Your API key was not accepted. Create a new one at https://app.usemuro.com/ustawienia and run: muro login` * `This needs 3 credits and you have 1. Top up at https://app.usemuro.com/plan` * `This will use 2 credits. Add --yes to confirm.` * `The photo is larger than 12 MB.` * `HEIC photos are converted automatically only on macOS. Save the photo as JPEG first.` The server-side messages are on [Errors](/reference/errors/). ## For AI agents [Section titled “For AI agents”](#for-ai-agents) The same features are available over MCP. See the [MCP overview](/mcp/overview/) and the [quickstart](/start/quickstart/). # MCP server overview > Connect an MCP client to the Muro paint server. Endpoints, the eight tools, server card, rate limits and the three ways to pay for paint tools. The Muro MCP server gives an AI agent real paint colours from 35 manufacturer catalogues (about 51,000 colours) and, with a Muro account or an x402 payment, can repaint a photo of a room, facade or roof. ## Endpoints [Section titled “Endpoints”](#endpoints) | URL | Transport | Sign-in | Use it for | | ------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | | `https://mcp.usemuro.com/mcp` | Streamable HTTP | None for the free tools. Optional `Authorization: Bearer muro_sk_…` header (a Muro API key) for the paid tools. | Clients that can send headers: CLIs, SDKs, Claude Code, Cursor. | | `https://mcp.usemuro.com/account/mcp` | Streamable HTTP | OAuth: the user signs in with their Muro account. | Connectors that cannot send headers, such as claude.ai and ChatGPT. See [/auth/oauth/](/auth/oauth/). | Both endpoints expose the same eight tools. The paid tools are always listed so that agents can discover them; they fail with an explanatory message when no payment method is available. ## Tools [Section titled “Tools”](#tools) | Tool | What it does | Cost | Reference | | --------------------- | --------------------------------------------------------------------- | ---------------------------------------- | ------------------------------------------------------------------ | | `search_paint_colors` | Find colours by name or code across all brands. | Free | [/mcp/tools/search-paint-colors/](/mcp/tools/search-paint-colors/) | | `get_paint_color` | Look up one colour by brand and exact name or code. | Free | [/mcp/tools/get-paint-color/](/mcp/tools/get-paint-color/) | | `find_equivalents` | Closest colours in other brands to a colour or hex value (CIEDE2000). | Free | [/mcp/tools/find-equivalents/](/mcp/tools/find-equivalents/) | | `list_brands` | List brands, optionally those sold in a country. | Free | [/mcp/tools/list-brands/](/mcp/tools/list-brands/) | | `visualize_room` | Repaint a photo in 1 to 12 colours. | Paid: 1 to 3 credits per colour, or x402 | [/mcp/tools/visualize-room/](/mcp/tools/visualize-room/) | | `get_visualization` | Fetch the colours of a `visualize_room` job that were not ready yet. | No extra cost | [/mcp/tools/get-visualization/](/mcp/tools/get-visualization/) | | `relight_room` | Relight a finished interior as day, evening or night. | Paid: 1 credit, or x402 | [/mcp/tools/relight-room/](/mcp/tools/relight-room/) | | `get_credits` | Show the credit balance and plan of the connected account. | Needs a Muro key | [/mcp/tools/get-credits/](/mcp/tools/get-credits/) | ## Server card and registry [Section titled “Server card and registry”](#server-card-and-registry) * Server card: . JSON with the transport URL, authentication options, rate limits and the full tool list (names, titles, descriptions). * MCP Registry name: `com.usemuro/paint-colors` (title “Muro Paint Colors”, both endpoints above are listed as `streamable-http` remotes). * A plain-text description is served at `GET https://mcp.usemuro.com/`. ## Rate limits [Section titled “Rate limits”](#rate-limits) Limits are per client IP and approximate. | Traffic | Limit | | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | | Requests to `/mcp` without an `Authorization` header | 600 per 60 seconds | | Requests with an `Authorization` header (keyed calls), `/account/mcp`, and the OAuth endpoints (`/register`, `/authorize`, `/oauth/*`) | 60 per 60 seconds | `GET /`, the server card, and CORS preflight requests are not counted. When a limit is exceeded the server answers HTTP `429` with a `Retry-After: 60` header and a JSON-RPC error body: ```json { "jsonrpc": "2.0", "id": null, "error": { "code": -32000, "message": "Rate limit: 600 requests per minute per client. Retry in 60 seconds." } } ``` ## Paying for the paint tools [Section titled “Paying for the paint tools”](#paying-for-the-paint-tools) The free tools need nothing. `visualize_room` and `relight_room` spend money, in one of three ways. The server tries them in this order: a key on the connection, then x402, then it returns an error that says where to get a key. 1. **Muro API key (credits).** Create a key at `https://app.usemuro.com/ustawienia` and send it as `Authorization: Bearer muro_sk_…`. Painting is charged against the account’s credits: 1 credit per colour in `standard`, 2 in `hd`, 3 in `ultra`; `relight_room` costs 1. Details: [API keys](/auth/api-keys/). 2. **OAuth.** Connect to `https://mcp.usemuro.com/account/mcp` and sign in with a Muro account. Same credits as a key. See [/auth/oauth/](/auth/oauth/). 3. **x402.** An agent without an account pays per call in USDC on Base. Prices: $0.25 (`standard`), $0.50 (`hd`) or $0.75 (`ultra`) per colour, and $0.25 per `relight_room`. `get_visualization` is free under x402. `get_credits` is not sold over x402. See [/x402/](/x402/). # find_equivalents > Reference for the find_equivalents MCP tool. Find the closest colours in other paint brands to a colour or hex value, ranked by CIEDE2000. Free. `find_equivalents` finds the closest colours in other brands to a given paint colour or hex value, for example “Behr equivalent of Farrow & Ball Hague Blue” or “which Benjamin Moore is closest to #D1CBC1”. Give either `brand` plus `name_or_code`, or `hex`. Distance is CIEDE2000 ΔE. By default it returns the single best match per brand, closest first. Pass `brands` to restrict the search; with one brand you get several options from it. **Cost:** Free. No key needed. ## Parameters [Section titled “Parameters”](#parameters) | Name | Type | Required | Default | Description | | -------------- | -------------------------------------------------- | -------- | ---------------- | -------------------------------------------------------------------------- | | `brand` | string, max 60 chars | no | | Brand of the source colour. Use together with `name_or_code`. | | `name_or_code` | string, max 100 chars | no | | Name or code of the source colour. | | `hex` | string, max 7 chars | no | | Source colour as hex, e.g. `#3D4E57`, instead of `brand` + `name_or_code`. | | `brands` | array of strings (max 60 chars each), max 20 items | no | all other brands | Only search these brands, e.g. `["Behr", "Sherwin-Williams"]`. | | `limit` | integer, 1 to 30 | no | 8 | Maximum results. | If `hex` is given it is used and `brand`/`name_or_code` are ignored. With neither `hex` nor both `brand` and `name_or_code`, the tool returns an error. ## Returns [Section titled “Returns”](#returns) One text content item holding a JSON object: | Field | Description | | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `source_color` | The source colour: the catalogue colour (all colour fields) or `{ "hex": "#…" }`. | | `note` | Present if the source name exists in several catalogues of the same brand; says which one was matched. | | `count` | Number of equivalents. | | `equivalents` | Colours (same fields as in [/mcp/tools/search-paint-colors/](/mcp/tools/search-paint-colors/)) plus `delta_e` (CIEDE2000 ΔE) and `match` (verdict). | | `hint` | Present when nothing is within ΔE 6: `Nothing within ΔE 6 in the requested brands.` | | `caveat` | On-wall results depend on base, sheen and tinting; test a sample. | | `found`, `message`, `suggestions` | Returned instead of the above if the source colour is not in the catalogue. | Verdicts (`match`): under 1 “practically identical”, under 2 “very close”, under 3.5 “close”, otherwise “similar”. Nothing above ΔE 6 is returned. A catalogue source colour skips its own brand and that brand’s sister catalogues. ## Example [Section titled “Example”](#example) Arguments: ```json { "brand": "Farrow & Ball", "name_or_code": "Hague Blue", "brands": ["Behr", "Sherwin-Williams"], "limit": 2 } ``` Result (captured from `https://mcp.usemuro.com/mcp`, attribution fields trimmed): ```json { "source_color": { "brand": "Farrow & Ball", "brand_id": "farrow_ball", "name": "Hague Blue", "hex": "#3D4E57", "lrv": 29.4, "category": "blue", "collection": "Main Collection", "code": "30", "url": "https://usemuro.com/en/colors/farrow_ball/hague-blue" }, "count": 2, "equivalents": [ { "brand": "Behr", "brand_id": "behr", "name": "Orion Gray", "hex": "#3D4C55", "lrv": 28.8, "category": "blue", "collection": "Main Collection", "code": "N510-6", "url": "https://usemuro.com/en/colors/behr/orion-gray", "delta_e": 0.98, "match": "practically identical" }, { "brand": "Sherwin-Williams", "brand_id": "sherwin_williams", "name": "Sea Serpent", "hex": "#3E4B54", "lrv": 28.6, "category": "blue", "collection": "Sherwin-Williams-all", "code": "SW 7615", "url": "https://usemuro.com/en/colors/sherwin_williams/sea-serpent", "delta_e": 1.82, "match": "very close" } ], "caveat": "Screen colours are approximations. On the wall the result depends on the paint base, sheen and tinting, so test a sample before buying." } ``` ## Notes [Section titled “Notes”](#notes) * Always pass on the caveat: the colour on the wall depends on the paint base, sheen and tinting. A low ΔE means the screen values are close, not that two paints look identical on a wall. * An invalid `hex` returns an error: `Use six hex digits like #3D4E57.` # get_credits > Reference for the get_credits MCP tool. Show the Muro credit balance and plan of the connected account. Needs a Muro API key or OAuth sign-in. `get_credits` shows the Muro credit balance and plan of the connected account. Use it before [/mcp/tools/visualize-room/](/mcp/tools/visualize-room/) to check that the account can afford the painting. Painting costs 1 credit per colour in `standard`, 2 in `hd` and 3 in `ultra`. **Cost:** Free to call, but it needs a Muro API key or an OAuth sign-in on the connection. It is not sold over x402, so an agent paying with x402 cannot use it. ## Parameters [Section titled “Parameters”](#parameters) None. Send an empty object. ## Returns [Section titled “Returns”](#returns) One text content item: ```text credits on the plan. Painting costs 1 credit per colour in standard, 2 in hd, 3 in ultra. Top up or change plan at https://app.usemuro.com/plan. ``` ## Example [Section titled “Example”](#example) Arguments: ```json {} ``` Result (illustrative; the values are made up): ```text 20 credits on the free plan. Painting costs 1 credit per colour in standard, 2 in hd, 3 in ultra. Top up or change plan at https://app.usemuro.com/plan. ``` Without a key (captured from `https://mcp.usemuro.com/mcp`, `isError: true`): ```text Painting a photo needs a Muro account with credits. Create an API key at https://app.usemuro.com/ustawienia (Settings → API keys) and add it to this connection as the header "Authorization: Bearer muro_sk_…". Looking up paint colours stays free without a key. ``` ## Notes [Section titled “Notes”](#notes) * A rejected key (missing, mistyped or revoked) returns an error that says so, followed by the same instructions. * Keyed calls fall under the stricter rate limit; see [/mcp/overview/](/mcp/overview/). # get_paint_color > Reference for the get_paint_color MCP tool. Look up one paint colour by brand and exact name or code. Free. `get_paint_color` looks up one paint colour by brand and exact name or code, for example brand “Sherwin-Williams” with “SW 7029” or “Agreeable Gray”, or brand “Farrow & Ball” with “Hague Blue” or “30”. Case, spacing and accents are ignored. If nothing matches exactly, it returns close suggestions instead. **Cost:** Free. No key needed. ## Parameters [Section titled “Parameters”](#parameters) | Name | Type | Required | Default | Description | | -------------- | ---------------------- | -------- | ------- | ----------------------------------------------------- | | `brand` | string, 1 to 60 chars | yes | | Brand name, e.g. “Behr”, “Benjamin Moore”, “Śnieżka”. | | `name_or_code` | string, 1 to 100 chars | yes | | Exact colour name or manufacturer code. | ## Returns [Section titled “Returns”](#returns) One text content item holding a JSON object. Found: | Field | Description | | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `found` | `true`. | | `colors` | Matching colours (same fields as in [/mcp/tools/search-paint-colors/](/mcp/tools/search-paint-colors/)). A brand sold in several markets may return one match per market. | Not found: | Field | Description | | ------------- | ------------------------------------------------------- | | `found` | `false`. | | `message` | `No colour named or coded "" in .` | | `suggestions` | Close colours. | Both shapes also carry `see_on_your_wall` and `data_source`. ## Example [Section titled “Example”](#example) Arguments: ```json { "brand": "Sherwin-Williams", "name_or_code": "SW 7029" } ``` Result (captured from `https://mcp.usemuro.com/mcp`, attribution fields trimmed): ```json { "found": true, "colors": [ { "brand": "Sherwin-Williams", "brand_id": "sherwin_williams", "name": "Agreeable Gray", "hex": "#D1CBC1", "lrv": 79.8, "category": "neutral", "collection": "Sherwin-Williams-all", "code": "SW 7029", "url": "https://usemuro.com/en/colors/sherwin_williams/agreeable-gray" } ] } ``` ## Notes [Section titled “Notes”](#notes) * A miss is not an error: the call succeeds with `found: false`. Check `found`. * If you do not know the exact name, use [/mcp/tools/search-paint-colors/](/mcp/tools/search-paint-colors/). * Hex values are screen approximations of real paint. # get_visualization > Reference for the get_visualization MCP tool. Fetch the colours of a visualize_room job that were not ready yet. No extra cost. `get_visualization` fetches the colours of a [/mcp/tools/visualize-room/](/mcp/tools/visualize-room/) job that were not ready yet, by `job_id` and `project_id`. It waits up to about 25 seconds. Call it again if the result still reports unfinished colours. **Cost:** Free. It costs no credits. Under x402 it also runs without a payment: the job id is the proof of purchase. It still needs a key or x402 to be enabled on the connection, and the job must belong to the account that ran it (under x402, to Muro’s service account). ## Parameters [Section titled “Parameters”](#parameters) | Name | Type | Required | Default | Description | | -------------- | -------------------------------------------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------- | | `job_id` | string, 1 to 100 chars | yes | | `job_id` from `visualize_room`. | | `project_id` | string, 1 to 100 chars | yes | | `project_id` from `visualize_room`. | | `country` | string, max 40 chars | no | | Where the user buys paint, e.g. “PL”, “DE”, “US”: brands sold there come first in the shopping list. | | `match_brands` | array of strings (max 60 chars each), max 10 items | no | all brands | Only list paints from these brands. | | `matches` | integer, 0 to 10 | no | 5 | Paints to list per colour. `0` means no shopping list. | ## Returns [Section titled “Returns”](#returns) Same shape as [/mcp/tools/visualize-room/](/mcp/tools/visualize-room/): MCP `image` content for each finished colour with its caption and shopping list, a final status text, and `structuredContent` with `project_id`, `job_id`, `status`, `result_url` and `colors`. The `cost` and `credits_left` fields are not included, because nothing is charged. If colours are still running, the status text says `Painted N of M so far` and repeats the call to make. Colours that failed are listed with their error. ## Example [Section titled “Example”](#example) Arguments: ```json { "job_id": "job_456", "project_id": "proj_123", "country": "US" } ``` The result has the same shape as in `visualize_room`. Calling with ids that do not exist (captured, no key on the connection and x402 enabled) returns: ```text Muro could not find that project or job. It may belong to another account. ``` with `isError: true`. ## Notes [Section titled “Notes”](#notes) * Use the `job_id` and `project_id` exactly as `visualize_room` returned them. * The shopping list is recomputed from the catalogue on each call, so you can change `country`, `match_brands` and `matches` between calls. * Without a key and without x402 enabled, the tool returns the same “needs a Muro account” error as the other paid tools. # list_brands > Reference for the list_brands MCP tool. List the paint brands in the Muro database, or the brands sold in a given country. Free. `list_brands` lists the paint brands in the database with their number of colours and a brand page URL. With `country` (an ISO code like “DE”, “PL”, “US”, “GB”, or a name like “Germany”) it returns the brands sold there, in order of local relevance. **Cost:** Free. No key needed. ## Parameters [Section titled “Parameters”](#parameters) | Name | Type | Required | Default | Description | | --------- | -------------------- | -------- | ---------- | ------------------------------------------------ | | `country` | string, max 40 chars | no | all brands | Country code or name, e.g. “US”, “DE”, “Poland”. | ## Returns [Section titled “Returns”](#returns) One text content item holding a JSON object: | Field | Description | | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | | `market` | The country as resolved, when `country` was given. | | `brands` | Array of brands: `brand`, `brand_id`, `country`, `colors` (number of colours), `collections` (number of collections), `url` (brand page on usemuro.com). | | `other_brands` | With `country`: how many further brands exist that are not sold there. | | `see_on_your_wall`, `data_source` | Attribution strings. | ## Example [Section titled “Example”](#example) Arguments: ```json { "country": "DE" } ``` Result (captured from `https://mcp.usemuro.com/mcp`; the list is trimmed to two brands and attribution fields are omitted): ```json { "market": "DE", "brands": [ { "brand": "Alpina", "brand_id": "alpina", "country": "DE", "colors": 186, "collections": 7, "url": "https://usemuro.com/en/colors/alpina" }, { "brand": "Caparol", "brand_id": "caparol", "country": "DE", "colors": 2774, "collections": 27, "url": "https://usemuro.com/en/colors/caparol" } ], "other_brands": 27 } ``` The real response listed eight brands for DE. ## Notes [Section titled “Notes”](#notes) * Use the returned `brand` names as the `brand` / `brands` arguments of the other tools. Some brands exist per market (for example “Sikkens (DE)”). * The same country values work for the `country` argument of [/mcp/tools/visualize-room/](/mcp/tools/visualize-room/), which puts brands sold there first in the shopping list. # relight_room > Reference for the relight_room MCP tool. Relight a finished interior visualization as day, evening or night, with lamps on or off. Paid. `relight_room` relights a finished interior visualization as day, evening or night, with lamps on or off, keeping the wall colour. It needs the `project_id` and the `color_key` returned by [/mcp/tools/visualize-room/](/mcp/tools/visualize-room/). Interiors only. **Cost:** * Muro credits: 1 credit per call. * x402 price: $0.25 per call (USDC on Base). See [/x402/](/x402/). ## Parameters [Section titled “Parameters”](#parameters) | Name | Type | Required | Default | Description | | ------------ | ------------------------------- | -------- | ------- | ----------------------------------------------- | | `project_id` | string, 1 to 100 chars | yes | | `project_id` from `visualize_room`. | | `color_key` | string, 1 to 40 chars | yes | | `color_key` of the painted result, e.g. `"c1"`. | | `time` | enum: `day`, `evening`, `night` | yes | | Time of day. | | `lamps` | boolean | no | `false` | Lamps on. | ## Returns [Section titled “Returns”](#returns) Three MCP content items: 1. Text: `[, lamps on] — color_key ""`. 2. An **image** item (base64 `data` and `mimeType`) with the relit photo. 3. Text with the full-resolution link `https://app.usemuro.com/wynik/`. When paid with credits it is prefixed with `Cost: N credit(s), M left.`; under x402 the cost is omitted. There is no `structuredContent`. ## Example [Section titled “Example”](#example) Arguments: ```json { "project_id": "proj_123", "color_key": "c1", "time": "evening", "lamps": true } ``` Result text items for a successful call (illustrative; the image item is omitted): ```text evening, lamps on — color_key "c1" Cost: 1 credit, 17 left. Full resolution: https://app.usemuro.com/wynik/proj_123 ``` With x402 enabled and no payment attached, the call returns (captured) an error with the payment requirements: ```text This call costs 0.25 USDC on Base, paid with x402. Pay with an x402-capable client, or use a Muro API key (https://app.usemuro.com/ustawienia) to pay with Muro credits instead. ``` ## Notes [Section titled “Notes”](#notes) * Run `visualize_room` first, with `surface: "interior"`; the `color_key` values (`c1`, `c2`, …) follow the order of the `colors` you sent. * The project must belong to the account that ran it. Otherwise the call fails with an error and, under x402, is not charged. * Without a key and without x402 enabled, the tool returns an error that says where to create a Muro API key. # search_paint_colors > Reference for the search_paint_colors MCP tool. Find paint colours by name or code across all brands. Free. `search_paint_colors` finds paint colours by name or code across all brands, for example “Hague Blue”, “SW 7029”, “agreeable gray” or “grün”. Matching ignores case and accents (“sniezny” finds “Śnieżny”) and every word may be a prefix. You can restrict the search to one brand. To match a hex value or a colour from another brand, use [/mcp/tools/find-equivalents/](/mcp/tools/find-equivalents/) instead. **Cost:** Free. No key needed. ## Parameters [Section titled “Parameters”](#parameters) | Name | Type | Required | Default | Description | | ------- | ---------------------- | -------- | ---------- | ------------------------------------------------------------ | | `query` | string, 1 to 100 chars | yes | | Colour name or code, or part of it. | | `brand` | string, max 60 chars | no | all brands | Brand name, e.g. “Benjamin Moore”, “Farrow & Ball”, “Dulux”. | | `limit` | integer, 1 to 50 | no | 10 | Maximum results. | ## Returns [Section titled “Returns”](#returns) One text content item holding a JSON object: | Field | Description | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `query` | The query as sent. | | `brand` | The brand filter, present only if you sent one. | | `count` | Number of colours returned. | | `colors` | Array of colours: `brand`, `brand_id`, `name`, `hex`, `lrv` (light reflectance value, 0 = black, 100 = white), `category`, `collection`, `code` (when the brand has one), `url` (colour page on usemuro.com). | | `hint` | Present when `count` is 0: a suggestion for a better query. | | `note`, `partial_matches` | Present when no colour matches every word but some match part of the query. `colors` is then empty and `partial_matches` lists colours that match some of the words. | | `see_on_your_wall`, `data_source` | Attribution strings added to every free-tool reply. | ## Example [Section titled “Example”](#example) Arguments: ```json { "query": "hague blue", "limit": 2 } ``` Result (captured from `https://mcp.usemuro.com/mcp`): ```json { "query": "hague blue", "count": 1, "colors": [ { "brand": "Farrow & Ball", "brand_id": "farrow_ball", "name": "Hague Blue", "hex": "#3D4E57", "lrv": 29.4, "category": "blue", "collection": "Main Collection", "code": "30", "url": "https://usemuro.com/en/colors/farrow_ball/hague-blue" } ], "see_on_your_wall": "Preview it on a photo of your own room with Muro (iPhone, iPad and web): https://app.usemuro.com · App Store: https://apps.apple.com/app/id6757682733", "data_source": "Muro paint colour database (usemuro.com), compiled from manufacturers’ published colour catalogues." } ``` ## Notes [Section titled “Notes”](#notes) * If `query` is a hex value starting with `#`, the tool returns an error (`isError: true`) telling you to use `find_equivalents` with `hex`. * A brand sold in several markets (Dulux UK/PL, Sikkens NL/DE/IT, Beckers SE/PL) can return one colour per market. * Hex values are screen approximations. On the wall the colour depends on base, sheen and tinting. * If the database is unavailable the tool returns an error asking you to retry. # visualize_room > Reference for the visualize_room MCP tool. Repaint the walls in a photo of a room, facade or roof in 1 to 12 colours, with a shopping list of real paints. Paid. `visualize_room` repaints the walls in a photo of a room, facade or roof in 1 to 12 colours at once and returns one image per colour. Give the photo as `image_url` (a public link) or `image_base64`. Give each colour as `brand` + `name_or_code` from the catalogue (e.g. “Farrow & Ball” + “Hague Blue”) or as `hex`. RAL works as brand “RAL” + “9005” or just “RAL 9005”. Without a photo it paints Muro’s sample room (or facade, or roof). Every colour comes with a shopping list: the closest real paints from several brands, with ΔE and a verdict. The tool waits up to about 45 seconds. If some colours are still being painted, it returns a `job_id` and `project_id`; fetch the rest with [/mcp/tools/get-visualization/](/mcp/tools/get-visualization/). **Cost:** * Muro credits (API key or OAuth): 1 credit per colour in `standard`, 2 in `hd`, 3 in `ultra`. Tell the user the cost before calling. * x402 price: $0.25 per colour in `standard`, $0.50 in `hd`, $0.75 in `ultra` (USDC on Base). The price is computed from the number of colours and `quality`. See [/x402/](/x402/). ## Parameters [Section titled “Parameters”](#parameters) | Name | Type | Required | Default | Description | | --------------- | -------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------------------------------------------------------- | | `image_url` | string, max 2048 chars | no | sample photo | Public link to the photo (JPEG, PNG or WebP, up to 12 MB). Leave out both image fields to paint Muro’s sample room. | | `image_base64` | string | no | | The photo as base64 or a `data:` URL, instead of `image_url`. | | `colors` | array of colour objects, 1 to 12 items | yes | | Each colour is painted as a separate image. See below. | | `surface` | enum: `interior`, `facade`, `roof` | no | `interior` | What is in the photo. | | `quality` | enum: `standard`, `hd`, `ultra` | no | `standard` | `standard` is about 1K (1 credit per colour), `hd` about 2K (2), `ultra` about 4K (3, plan permitting). | | `paint_ceiling` | boolean | no | `false` | Interiors only: paint the ceiling too. | | `country` | string, max 40 chars | no | | Where the user buys paint, e.g. “PL”, “DE”, “US”. Brands sold there come first in the shopping list. | | `match_brands` | array of strings (max 60 chars each), max 10 items | no | all brands | Only list paints from these brands, e.g. `["Dulux", "Śnieżka"]`. | | `matches` | integer, 0 to 10 | no | 5 | Paints to list per colour. `0` means no shopping list. | Colour object: | Name | Type | Required | Description | | -------------- | --------------------- | ------------------------- | ------------------------------------------------------------- | | `brand` | string, max 60 chars | with `name_or_code` | Paint brand, e.g. “Farrow & Ball”. | | `name_or_code` | string, max 100 chars | with `brand` | Colour name or code in that brand, e.g. “Hague Blue” or “30”. | | `hex` | string, max 7 chars | instead of the pair above | Colour as hex, e.g. `#3D4E57`. | | `label` | string, max 60 chars | no | Display name for the colour (useful for hex colours). | Each colour needs either `brand` + `name_or_code`, or `hex`. If both are present, `brand` + `name_or_code` is used. ## Returns [Section titled “Returns”](#returns) A result with MCP content items and `structuredContent`. **Content items**, in this order: 1. For each painted colour: a text item ` () — color_key ""`, then an **image** item (MCP `image` content: base64 `data` and `mimeType`), then a text item with the shopping list (`Paints to buy (closest first): …`). 2. A final text item with status lines: whether the sample room was used, progress if the job is not finished (`Painted 1 of 3 so far. Call get_visualization with job_id … and project_id …`), colours that could not be painted, refunded credits, `Cost: N credits, M left.` (credit payments only), the full-resolution link `https://app.usemuro.com/wynik/`, and a pointer to `relight_room`. Images larger than 1.5 MB are not inlined; the text item says so and links to the full-resolution page instead. **`structuredContent`:** | Field | Description | | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `project_id` | Muro project. Needed by `get_visualization` and `relight_room`. | | `job_id` | Painting job. Needed by `get_visualization`. | | `status` | Job status, e.g. `done`, `failed` or still running. | | `cost`, `credits_left` | Credits charged and left. Omitted under x402. | | `result_url` | `https://app.usemuro.com/wynik/`: full resolution, before/after slider, paint codes. | | `colors` | One entry per colour: `key` (`c1`, `c2`, … in the order sent), `name`, `brand`, `code`, `hex`, `image` (boolean, whether a result image exists), `error` (if it failed), `shopping_list`. | Shopping list item: `brand`, `brand_id`, `name`, `code`, `hex`, `delta_e`, `match` (“practically identical”, “very close”, “close” or “similar”), `url`, `local` (sold in `country`; always `false` without `country`). Nothing above ΔE 6 is listed; a catalogue colour skips its own brand. ## Example [Section titled “Example”](#example) Arguments: ```json { "image_url": "https://example.com/living-room.jpg", "colors": [ { "brand": "Farrow & Ball", "name_or_code": "Hague Blue" }, { "hex": "#D1CBC1", "label": "Warm greige" } ], "surface": "interior", "quality": "standard", "country": "US" } ``` Illustrative `structuredContent` (shape taken from the source; values are made up, because this tool cannot be called without paying): ```json { "project_id": "proj_123", "job_id": "job_456", "status": "done", "cost": 2, "credits_left": 18, "result_url": "https://app.usemuro.com/wynik/proj_123", "colors": [ { "key": "c1", "name": "Hague Blue", "brand": "Farrow & Ball", "code": "30", "hex": "#3D4E57", "image": true, "shopping_list": [ { "brand": "Behr", "brand_id": "behr", "name": "Orion Gray", "code": "N510-6", "hex": "#3D4C55", "delta_e": 0.98, "match": "practically identical", "url": "https://usemuro.com/en/colors/behr/orion-gray", "local": false } ] } ] } ``` Without a Muro key and without x402 payment, the call fails with an error that points to key creation. With x402 enabled and no payment attached, it returns the payment requirements (captured response for one colour in `standard`): ```text This call costs 0.25 USDC on Base, paid with x402. Pay with an x402-capable client, or use a Muro API key (https://app.usemuro.com/ustawienia) to pay with Muro credits instead. ``` followed by a second text item with the JSON payment requirements, also available in `_meta["x402/error"]`: ```json { "x402Version": 2, "error": "PAYMENT_REQUIRED", "resource": { "url": "x402://visualize_room", "description": "Paint a room photo", "mimeType": "application/json" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "250000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x681F7E6B36a7E12d728d2bF2db3aD55FF250F564", "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2" } } ] } ``` ## Notes [Section titled “Notes”](#notes) * **Job flow.** If the result says some colours are still being painted, call [/mcp/tools/get-visualization/](/mcp/tools/get-visualization/) with the `job_id` and `project_id`. The colours already painted are charged up front; the rest will finish. * **Validation before spending.** Colours are resolved against the catalogue first, then the account balance is checked, then the photo is fetched. A bad colour, an unknown brand, a hex typo or a balance too low returns an error and costs nothing. Errors for unknown colours include suggestions. * **Duplicates.** The same hex twice in one call is rejected, because each colour is charged. * **Failures.** Colours that fail are reported in the result and refunded. Under x402 the payment is settled only if every colour was delivered; otherwise the result ends with `You were not charged: the x402 payment was not settled.` * **Not enough credits.** The error states the cost (`colours × credits per colour`), the balance, and where to top up (`https://app.usemuro.com/plan`). * **Ceiling.** `paint_ceiling` applies to interiors only. * **Colour accuracy.** Painted images and hex values approximate real paint. On the wall the colour depends on base, sheen and tinting; test a sample before buying. * **Relight.** To see an interior at another time of day, use [/mcp/tools/relight-room/](/mcp/tools/relight-room/) with `project_id` and a `color_key`. # Colour data > Where Muro's 51,000+ paint colours come from, which brands and markets are covered, what hex, LRV and ΔE mean, and their limits. ## Sources [Section titled “Sources”](#sources) Colours are compiled from the manufacturers’ published colour catalogues: official swatch files, colour cards and their websites. They are merged into one Muro paint colour database. Brand names and colour names belong to their owners. Muro is not affiliated with any paint manufacturer. ## Scale [Section titled “Scale”](#scale) As of 2026-10-01, `list_brands` returns **35 catalogues** with **51,369 colours**, across the US, UK, DACH, Poland, France, Spain, Italy, Scandinavia and Benelux (9 regions). The count is of catalogues, not of companies: Dulux, Sikkens and Beckers are each split per market (see below), so there are 31 distinct brand names. | Market | Catalogues (colours) | | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | US | Behr (4,656), Benjamin Moore (4,118), Vista Paint (2,785), PPG Paints (2,088), Valspar (1,764), Dunn-Edwards (1,696), Sherwin-Williams (1,526) | | UK | Dulux (GB) (2,254), Farrow & Ball (132) | | Germany | Caparol (2,774), Sikkens (DE) (1,560), Brillux (1,514), Sto (800), Keim (264), RAL Colors (216), Alpina (186), Schöner Wohnen (23) | | Poland | Dulux (PL) (2,802), Śnieżka (2,044), Dekoral (324), Jedynka (312), Beckers (PL) (189), Magnat (170) | | France | Zolpan (2,965), Tollens (1,569) | | Spain | Titanlux (4,101), Bruguer (415), Procolor (359) | | Nordics | Tikkurila (FI, 3,319), Flügger (DK, 1,392), Jotun (NO, 941), Beckers (SE) (210) | | Benelux | Sikkens (NL) (1,380), Flexa (NL, 397) | | Italy | Sikkens (IT) (124) | The numbers change when the database is refreshed. Call [`list_brands`](/mcp/tools/list-brands/) for the current list; with `country` it returns the brands sold there, most relevant first. Markets: US, GB, DE (also AT/CH), PL, FR, ES, IT, NL (also BE/LU), SE, NO, DK, FI. ## Market-specific brands [Section titled “Market-specific brands”](#market-specific-brands) A brand sold in several markets has a separate catalogue per market, because the palettes and codes differ. Examples: Dulux UK and Dulux PL, Sikkens NL, DE and IT, Beckers SE and PL. [`get_paint_color`](/mcp/tools/get-paint-color/) returns one match per market. Equivalents and shopping lists can be limited to a market with `country`. ## What each colour carries [Section titled “What each colour carries”](#what-each-colour-carries) * `brand`, `name`, `code` and `collection` * `hex`: the colour as sRGB * `lrv`: light reflectance value, when the manufacturer publishes it, from 0 (black) to 100 (white). Higher LRV means more light reflected * `url`: its page on usemuro.com, in the form `https://usemuro.com/en/colors//` Every response also carries `see_on_your_wall` and `data_source`. ## Hex values are approximations [Section titled “Hex values are approximations”](#hex-values-are-approximations) Hex values are screen approximations of real paint. On the wall the result depends on the paint base, sheen and tinting. Test a sample before you buy. Every equivalents result includes this caveat. ## ΔE: how close is close [Section titled “ΔE: how close is close”](#δe-how-close-is-close) [`find_equivalents`](/mcp/tools/find-equivalents/) measures the distance between two colours with CIEDE2000 (ΔE), the standard formula for how different two colours look to a person. Colours are compared in CIELAB, converted from sRGB. | ΔE | Verdict | What it means | | ----- | --------------------- | ------------------------------------------- | | < 1 | Practically identical | The eye cannot tell them apart on a swatch. | | < 2 | Very close | Visible only side by side. | | < 3.5 | Close | A noticeable but small difference. | | ≤ 6 | Similar | Same family. | Nothing above ΔE 6 is returned. By default you get one result per brand. Restricted to a single brand, you get several options from it. Example: Farrow & Ball Hague Blue (`#3D4E57`) against Śnieżka S 7020-B10G is ΔE 0.49 (practically identical), against Dulux (PL) S0.16.22 is 1.35 (very close). ## Search behaviour [Section titled “Search behaviour”](#search-behaviour) [`search_paint_colors`](/mcp/tools/search-paint-colors/) ignores case and accents (`grun` finds *Grün*), lets every word be a prefix, and treats `SW7029` like `SW 7029`. # Errors > The error responses a Muro MCP client can get, with the exact messages, what causes them and how to fix them. Almost every failure arrives as a normal MCP tool result with `isError: true` and a plain-English message written for the assistant to relay to the user. The one exception is the rate limit, which is an HTTP `429`. Messages below are quoted from the server. Where a message contains a value that varies (a number, a name), it is shown in `` or as an example. ## No key, or key rejected [Section titled “No key, or key rejected”](#no-key-or-key-rejected) A painting tool called with no key, a mistyped key, or a revoked key. **No key** (also returned when the `Authorization` header is not a `muro_sk_…` token, because such headers are ignored): ```text Painting a photo needs a Muro account with credits. Create an API key at https://app.usemuro.com/ustawienia (Settings → API keys) and add it to this connection as the header "Authorization: Bearer muro_sk_…". Looking up paint colours stays free without a key. ``` **Key rejected** (a well-formed key that Muro does not accept): ```text The Muro API key was rejected (missing, mistyped or revoked). Painting a photo needs a Muro account with credits. Create an API key at https://app.usemuro.com/ustawienia (Settings → API keys) and add it to this connection as the header "Authorization: Bearer muro_sk_…". Looking up paint colours stays free without a key. ``` Fix: create a new key and update the client. See [API keys](/auth/api-keys/). If an assistant connected through [Sign in with Muro](/auth/oauth/), a revoked connection ends here too: reconnect it. On `/account/mcp`, a client that has no valid OAuth token gets an HTTP `401` and starts the sign-in flow. ## Insufficient credits [Section titled “Insufficient credits”](#insufficient-credits) Checked before anything is uploaded or spent: ```text This needs credits ( colours × in ) and the account has . Top up or change plan at https://app.usemuro.com/plan. ``` For example: `This needs 6 credits (2 colours × 3 in ultra) and the account has 4. Top up or change plan at https://app.usemuro.com/plan.` If the balance changes between the check and the start of painting, Muro can refuse with: ```text Not enough Muro credits for this. Each colour costs 1 credit in Standard, 2 in HD and 3 in Ultra. Top up or change plan at https://app.usemuro.com/plan. ``` The [CLI](/cli/) checks first and prints `This needs credits and you have . Top up at https://app.usemuro.com/plan`. Prices: [Pricing and limits](/reference/pricing-limits/). ## Plan does not allow the quality [Section titled “Plan does not allow the quality”](#plan-does-not-allow-the-quality) HD needs Pro and Ultra needs Premium. Muro returns its own reason. If it gives none, the fallback is: ```text This quality is above the account’s plan. Try quality "standard", or upgrade at https://app.usemuro.com/plan. ``` Fix: use `quality: "standard"`, or upgrade. ## Photo problems [Section titled “Photo problems”](#photo-problems) | Cause | Message | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | Over 12 MB | `The photo is larger than 12 MB. Use a smaller photo.` | | Not JPEG, PNG or WebP (including HEIC) | `The photo must be a JPEG, PNG or WebP image.` | | Both `image_url` and `image_base64` | `Give either image_url or image_base64, not both.` | | Broken base64 | `image_base64 is not valid base64.` | | Not a URL | `image_url is not a valid URL.` | | Not http or https | `image_url must be an http or https link.` | | Private or local address | `image_url must point to a public website.` | | Photo hosted on usemuro.com | `Photos on usemuro.com cannot be fetched from here. Send the photo as image_base64, or link it from another host.` | | Host unreachable | `Could not download the photo from . Check that the link is public.` | | Host answered with an error | `Downloading the photo failed with HTTP . Check that the link is public.` | | More than 3 redirects | `image_url redirects too many times. Link to the image file itself.` | The type is checked from the file’s bytes. HEIC from an iPhone is not accepted by the server: convert it to JPEG first. The CLI does it on macOS. In claude.ai and ChatGPT, pass the photo as a link, not a pasted image. If you give neither `image_url` nor `image_base64` to `visualize_room`, it paints Muro’s sample room and says so: `Painted on Muro's sample room, because no photo was given. Send image_url or image_base64 to paint your own room.` ## Colour problems [Section titled “Colour problems”](#colour-problems) Checked for free before any credit is spent. | Cause | Message | | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | 0 or more than 12 colours | `Give 1 to 12 colours per visualization (got ).` | | Colour not in the brand | `No colour "" in . Did you mean: , …?` or `… Use search_paint_colors to find it, or pass its hex.` | | Bad hex | `"" is not a hex colour. Use six hex digits like #3D4E57.` | | Colour with neither hex nor brand | `Colour needs a hex, or brand and name_or_code.` | | Same colour twice | ` is in the list twice. Each colour is charged, so give each one once.` | | Unknown brand | `Unknown brand "". Brands in the database: .` | | Unknown market | `No market data for "". Markets: US, GB, DE (also AT/CH), PL, FR, ES, IT, NL (also BE/LU), SE, NO, DK, FI. Call without country for every brand.` | ## Project or job not found [Section titled “Project or job not found”](#project-or-job-not-found) ```text Muro could not find that project or job. It may belong to another account. ``` Check `job_id` and `project_id` from `visualize_room`, and that you use the same account. ## Job still running [Section titled “Job still running”](#job-still-running) Not an error. When colours are not ready after about 45 seconds, `visualize_room` returns the finished images and this line: ```text Painted of so far. Call get_visualization with job_id "" and project_id "" in a few seconds for the rest. ``` Call [`get_visualization`](/mcp/tools/get-visualization/). Each call waits up to about 25 seconds. ## Colours that failed [Section titled “Colours that failed”](#colours-that-failed) ```text These colours could not be painted: . credit(s) were refunded for the failures. ``` Failed colours are refunded. Under x402, a response with a failed colour is not settled (see below). ## Rate limit [Section titled “Rate limit”](#rate-limit) HTTP `429` with `Retry-After: 60` and a JSON-RPC body: ```json { "jsonrpc": "2.0", "id": null, "error": { "code": -32000, "message": "Rate limit: 600 requests per minute per client. Retry in 60 seconds." } } ``` The number is `600` for keyless traffic and `60` for requests with an `Authorization` header and for OAuth endpoints. See [Pricing and limits](/reference/pricing-limits/#rate-limits). ## x402 payment [Section titled “x402 payment”](#x402-payment) Under [x402](/x402/), a `visualize_room` or `relight_room` call without a payment returns `isError: true`, the requirements in `_meta["x402/error"]` and this text: ```text This call costs 0.25 USDC on Base, paid with x402. Pay with an x402-capable client, or use a Muro API key (https://app.usemuro.com/ustawienia) to pay with Muro credits instead. ``` The amount is the price of that call. If a payment was sent but not accepted, the text adds the reason, and `_meta["x402/error"].error` carries it: ```text This call costs 0.50 USDC on Base, paid with x402. The payment was not accepted (INVALID_PAYMENT). Pay with an x402-capable client, or use a Muro API key (https://app.usemuro.com/ustawienia) to pay with Muro credits instead. ``` | `error` value | Meaning | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | `PAYMENT_REQUIRED` | No payment on the call. Sign a USDC authorization and call again with `_meta["x402/payment"]`. | | `INVALID_PAYMENT` | The payment token could not be decoded, did not match the requirements, or was rejected. | | other facilitator reasons | The facilitator’s verification or settlement reason is passed through. `SETTLEMENT_FAILED` means settlement did not complete. | If painting fails, the result ends with `You were not charged: the x402 payment was not settled.` A payment that is still confirming on-chain does not withhold the images: the result carries `_meta["x402/payment-response"]` with `success: false`. ## Unreachable or unexpected failures [Section titled “Unreachable or unexpected failures”](#unreachable-or-unexpected-failures) | Cause | Message | | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Muro API unreachable | `Muro is not reachable right now. Try again in a minute.` | | Muro API error | `Muro had a problem with this request. Try again in a minute.` | | Muro rejected the request | the reason from Muro, or `Muro rejected the request as invalid.` | | Unexpected failure in a paid tool | `Something went wrong while painting. Nothing was charged for work that did not finish. Try again in a minute.` | | Colour database error | `The colour database is temporarily unavailable. Try again in a moment.` | # Pricing and limits > Credits and x402 prices per colour, photo formats and size, colours per call, timings and rate limits for the Muro MCP server and CLI. Colour data is free. Painting costs credits (with an API key or OAuth sign-in) or USDC (with [x402](/x402/)). ## Free [Section titled “Free”](#free) `search_paint_colors`, `get_paint_color`, `find_equivalents` and `list_brands`. No account, no key. ## Credits per colour [Section titled “Credits per colour”](#credits-per-colour) With an [API key](/auth/api-keys/) or [OAuth sign-in](/auth/oauth/), painting spends the credits of your Muro account, as in the app. | Quality | Resolution | Credits per colour | Plan needed | | ---------- | ---------- | ------------------ | ------------- | | `standard` | about 1K | 1 | Any plan | | `hd` | about 2K | 2 | Pro or higher | | `ultra` | about 4K | 3 | Premium | * A time-of-day version from `relight_room` costs **1 credit**. * `get_visualization` and `get_credits` cost nothing. * Credits are **held** before painting starts. A colour that fails is **refunded**. The response says how many credits came back. * There are no free trials. * A call is refused up front if the account lacks the credits (see [Errors](/reference/errors/)). ## x402 prices (USDC on Base) [Section titled “x402 prices (USDC on Base)”](#x402-prices-usdc-on-base) Without an account, an agent pays per call in USDC on Base mainnet (`eip155:8453`). Details are on the [x402](/x402/) page. | Call | Price | | -------------------------- | ------------------------------------------- | | `visualize_room`, Standard | 0.25 USDC per colour | | `visualize_room`, HD | 0.50 USDC per colour | | `visualize_room`, Ultra | 0.75 USDC per colour | | `relight_room` | 0.25 USDC | | `get_visualization` | Free: the `job_id` is the proof of purchase | | `get_credits` | Needs a Muro key (not sold through x402) | The price of a call is the number of colours times the per-colour price, for example 4 colours in HD is 2.00 USDC. The payment is settled only after the images are delivered, so if painting fails you are not charged. ## Photos [Section titled “Photos”](#photos) | | | | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | | Formats | JPEG, PNG, WebP | | Maximum size | 12 MB | | Given as | `image_url` (public link) or `image_base64` | | Surfaces | interior walls, facade, roof | | Not accepted by the server | HEIC/HEIF. The Muro app and web app convert it; the [CLI](/cli/) converts it on macOS; agents should send a JPEG | The format is detected from the file’s bytes, not from the claimed type. Links to usemuro.com itself cannot be fetched by the server: send the photo as `image_base64` or host it elsewhere. In claude.ai and ChatGPT a pasted image cannot be passed on to a tool, so give the photo as a link. ## Per call [Section titled “Per call”](#per-call) * **1 to 12 colours** per `visualize_room` call. Each colour is a separate painted image. * **Up to 100 photo uploads a day per account.** ## Timings [Section titled “Timings”](#timings) * About 30 seconds for two colours in Standard. * About 15 seconds for a time-of-day version. * `visualize_room` waits about 45 seconds. If colours are not ready, it returns a `job_id` and `project_id`. Call [`get_visualization`](/mcp/tools/get-visualization/) to collect the rest (each call waits up to about 25 seconds). The [CLI](/cli/) waits for the job for up to 15 minutes. ## Rate limits [Section titled “Rate limits”](#rate-limits) Limits are per client IP address and per 60 seconds. They are enforced per Cloudflare data centre, so they are approximate. | Traffic | Limit | | ----------------------------------------------------------------------------------------------------------------------- | ------------ | | Free colour calls, no `Authorization` header (including x402 calls) | 600 per 60 s | | Any request with an `Authorization` header (API key), and `/account/mcp`, `/register`, `/authorize`, `/oauth/*` (OAuth) | 60 per 60 s | The server card (`GET /.well-known/mcp.json`), the landing text at `GET /` and CORS preflight requests are not counted. Above the limit the server answers HTTP `429` with `Retry-After: 60`. See [Errors](/reference/errors/). The 600 limit is generous because hosted connectors such as claude.ai and ChatGPT share vendor IP addresses. ## Related [Section titled “Related”](#related) * [Quickstart](/start/quickstart/) * [`visualize_room`](/mcp/tools/visualize-room/) * [Errors](/reference/errors/) # Quickstart > Connect the Muro MCP server to Claude, ChatGPT, Cursor or any MCP client, look up a paint colour for free, then paint a photo. The Muro MCP server is public. The colour tools need no account and no key. Painting a photo needs either a Muro API key or an [x402](/x402/) payment. Endpoint (Streamable HTTP): ```text https://mcp.usemuro.com/mcp ``` ## 1. Add the server [Section titled “1. Add the server”](#1-add-the-server) Pick your client. ### Claude (claude.ai, Desktop, mobile) [Section titled “Claude (claude.ai, Desktop, mobile)”](#claude-claudeai-desktop-mobile) Settings → Connectors → *Add custom connector*. Use this URL and leave authentication empty: ```text https://mcp.usemuro.com/account/mcp ``` You sign in to Muro when you connect, which also unlocks the painting tools. See [Sign in with Muro (OAuth)](/auth/oauth/). ### Claude Code [Section titled “Claude Code”](#claude-code) ```bash claude mcp add --transport http muro-colors https://mcp.usemuro.com/mcp ``` ### ChatGPT [Section titled “ChatGPT”](#chatgpt) Settings → Apps & Connectors → Advanced → turn on *Developer mode*, then *Create* a connector with this URL and **OAuth**. You sign in to Muro when you connect. Availability of custom connectors depends on your OpenAI plan. ```text https://mcp.usemuro.com/account/mcp ``` ### Cursor [Section titled “Cursor”](#cursor) Add to `~/.cursor/mcp.json`, or to `.cursor/mcp.json` in a project: ```json { "mcpServers": { "muro-colors": { "url": "https://mcp.usemuro.com/mcp" } } } ``` ### VS Code (Copilot agent mode) [Section titled “VS Code (Copilot agent mode)”](#vs-code-copilot-agent-mode) Add to `.vscode/mcp.json`, then use it in agent mode: ```json { "servers": { "muro-colors": { "type": "http", "url": "https://mcp.usemuro.com/mcp" } } } ``` ### Any other client [Section titled “Any other client”](#any-other-client) Clients that speak Streamable HTTP take the endpoint above. Clients that only start local servers can bridge it: ```bash npx mcp-remote https://mcp.usemuro.com/mcp ``` ## 2. Try a free call [Section titled “2. Try a free call”](#2-try-a-free-call) Ask your assistant: > Search for the paint colour “agreeable gray”. It calls [`search_paint_colors`](/mcp/tools/search-paint-colors/) and returns Sherwin-Williams Agreeable Gray (SW 7029, `#D1CBC1`, LRV 79.8) with a link to its page on usemuro.com. Other questions to try: * What is the Benjamin Moore version of Farrow & Ball Hague Blue? * Find me a warm white from Dulux with LRV above 80. * Which paint brands are sold in Poland? * I have #D1CBC1 from a photo. Which Behr colour is closest? The four colour tools (`search_paint_colors`, `get_paint_color`, `find_equivalents`, `list_brands`) are free. See the [MCP overview](/mcp/overview/). ## 3. Paint a photo [Section titled “3. Paint a photo”](#3-paint-a-photo) `visualize_room`, `get_visualization`, `relight_room` and `get_credits` are listed for everyone, but a call without payment answers with where to get access. Two ways to pay: * **A Muro API key.** Painting spends the credits of your Muro account, the same as the app. Create a key and send it as a header: see [API keys](/auth/api-keys/). In claude.ai and ChatGPT, which cannot send a header, [sign in with Muro](/auth/oauth/) instead. * **x402, no account.** An agent pays per call in USDC on Base. See [x402](/x402/). Prices and limits are on [Pricing and limits](/reference/pricing-limits/). Photos must be JPEG, PNG or WebP, up to 12 MB, 1 to 12 colours per call. The tool is described at [`visualize_room`](/mcp/tools/visualize-room/). ## From the command line [Section titled “From the command line”](#from-the-command-line) The same catalogue, without an MCP client. Node 20 or newer: ```bash npx usemuro colors search "agreeable gray" ``` See the [CLI guide](/cli/) for painting from the terminal. # Pay per call with x402 > Use Muro's paid MCP tools without an account by paying in USDC on Base with x402. An agent without a Muro account can still paint room photos. `visualize_room` and `relight_room` accept payment per call in USDC on **Base mainnet** through [x402](https://x402.org), an open protocol for paying for API calls with a signed stablecoin transfer. You need no sign-up, API key or subscription. Your agent only needs a wallet holding USDC on Base and an x402-capable client. If the call carries a Muro API key or an OAuth session, x402 is not used: the call is paid from that account’s [credits](/reference/pricing-limits/). ## Prices [Section titled “Prices”](#prices) | Tool | Price | | --------------------------------------------------------------------------- | --------------------------------------------- | | `visualize_room`, Standard (≈1K) | 0.25 USDC per colour | | `visualize_room`, HD (≈2K) | 0.50 USDC per colour | | `visualize_room`, Ultra (≈4K) | 0.75 USDC per colour | | `relight_room` | 0.25 USDC | | `get_visualization` | Free (the `job_id` is the proof of purchase) | | `search_paint_colors`, `get_paint_color`, `find_equivalents`, `list_brands` | Free, no payment at all | | `get_credits` | Not available over x402; needs a Muro API key | The price of a `visualize_room` call depends on its arguments: 3 colours in HD cost 1.50 USDC. It is computed for each call and returned in the payment requirements, so the client always sees the exact amount before signing anything. ## How it works [Section titled “How it works”](#how-it-works) The flow follows the MCP x402 convention also used by Cloudflare’s `agents/x402`: payment data travels in the tool call’s `_meta`. 1. **Call the tool without payment.** Here: `visualize_room` with 2 colours in HD. The result has `isError: true`, a human-readable line such as `This call costs 1.00 USDC on Base, paid with x402.`, and the machine-readable requirements in `_meta["x402/error"]`: ```json { "x402Version": 2, "error": "PAYMENT_REQUIRED", "resource": { "url": "x402://visualize_room", "description": "Paint a room photo", "mimeType": "application/json" }, "accepts": [ { "scheme": "exact", "network": "eip155:8453", "amount": "1000000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x681F7E6B36a7E12d728d2bF2db3aD55FF250F564", "maxTimeoutSeconds": 300, "extra": { "name": "USD Coin", "version": "2" } } ] } ``` `amount` is in USDC base units (6 decimals): `1000000` is 1.00 USDC. `asset` is native USDC on Base, and `payTo` is Muro’s receiving wallet. 2. **Sign and retry.** The client signs an EIP-3009 `transferWithAuthorization` for that amount (the `exact` EVM scheme), base64-encodes the x402 payment payload, and repeats the same call with it in `_meta["x402/payment"]`. 3. **Muro verifies, paints, then settles.** The payment is verified first. Muro then does the work. The transfer is settled on-chain **only after the images were delivered**. The result carries `_meta["x402/payment-response"]`: ```json { "success": true, "transaction": "0x…", "network": "eip155:8453", "payer": "0x…" } ``` Payments are verified and settled by the [PayAI facilitator](https://facilitator.payai.network). ## What you are charged for [Section titled “What you are charged for”](#what-you-are-charged-for) * **A failed painting costs nothing.** If the work fails, or any colour fails, the payment is not settled and the result ends with `You were not charged: the x402 payment was not settled.` * **Colours still rendering count as delivered.** A long job can return before every image is ready; the payment settles and you fetch the rest with [`get_visualization`](/mcp/tools/get-visualization/) for free. * **Pending settlement.** If the on-chain transfer has not confirmed in time, you still get the images, with `"x402/payment-response": { "success": false, "errorReason": "settlement_pending" }`. The transfer will most likely land shortly after. * **Settlement refused.** If the facilitator rejects the settlement after the work was done, the result is withheld and you get a fresh payment requirement instead. * A payment that fails verification returns the requirements again, with the reason in `error` (and `payer`, when known), for example `INVALID_PAYMENT` for a token that is not valid base64 JSON. ## Clients [Section titled “Clients”](#clients) Any MCP client that implements the `_meta["x402/payment"]` convention can pay. For example, Cloudflare’s `agents` package has `withX402Client`, which wraps an MCP client, reads `x402/error`, asks for confirmation and retries with the payment. Clients that do not support x402 see the payment-required message and can fall back to a [Muro API key](/auth/api-keys/). ## Limits [Section titled “Limits”](#limits) x402 calls share the limits of keyed calls: 1 to 12 colours per call, photos up to 12 MB (JPEG, PNG or WebP) and the rate limits in [Pricing and limits](/reference/pricing-limits/).