RepairDesk MCP Server

An MCP (Model Context Protocol) server that gives any MCP-compatible AI assistant — Claude Code, Claude Desktop, Codex CLI, OpenCode, Cursor, Windsurf, or any other MCP client — direct, read/write access to your RepairDesk shop data. Point it at your store's API key and start asking things like "look up ticket T-15423", "what's overdue on invoice 8821", or "assign the iPhone screen job to Dave".

Not an official RepairDesk product — an independent tool built by a RepairDesk shop for RepairDesk shops. No warranty, use at your own risk (see License) — but it's in daily use running a real repair shop's ticket queue, not a proof of concept.

Contents

• What you can actually do with this

• Tools reference

• What this is not

• Quick start

• Manual setup

• All configuration options

• Troubleshooting

• FAQ

• Security

Related MCP server: TicketAI

What you can actually do with this

Once it's wired into your AI assistant, you can just talk to your RepairDesk data instead of clicking through the web UI. Some real examples:

Front counter / triage

• "Look up ticket T-15423" — full ticket detail: customer, device, per-device status, notes.

• "What's the status on Sarah Miller's phone?" — searches tickets by customer name/keyword.

• "Show me everything that's Pending or Waiting for Parts" — filter tickets by status.

• "What's assigned to Dave right now?" — filter tickets by technician.

• "Pull up John's contact details" — customer lookup by name, phone, or email.

Workflow / bench work

• "Add a diagnostic note to T-15423: replaced screen, battery tested OK"

• "Assign ticket T-15490 to Dave"

• "Mark T-15423 as Repaired" — the server will ask you to confirm first, and flags that this status auto-fires a customer SMS/email in RepairDesk.

• "Create a ticket for this customer: iPhone 13, screen replacement" — again, confirmation required before it actually creates anything.

Money / admin

• "Which invoices are still unpaid from last month?"

• "What's the outstanding balance on invoice 8821?"

• "Do we have an iPhone 13 battery in stock?" — inventory search.

• "List all our technicians" / "What payment methods do we have set up?"

• "What repair categories/device types do we have configured?" — useful context when building a ticket or diagnosing what a device model even is in your system.

Because this runs through an actual AI assistant rather than a fixed dashboard, you can chain these naturally — "find any overdue invoices for customers with a ticket still open" — and the assistant works it out across tools instead of you cross-referencing two screens by hand.

Tools reference

Safety rail: repairdesk_tickets_write requires confirmed: true before applying a status change, and warns when the target status is one RepairDesk auto-notifies the customer on (Repaired, Ready for Pickup, Completed, Waiting on Customer, Waiting For Quote, Cancelled). You don't need to do anything for this to work — just answer "yes" when your assistant relays the confirmation prompt.

Handy detail: ticket lookups/writes accept either RepairDesk's order ID format (T-15423) or the internal numeric ticket ID — you never need to know which one you have, the server resolves it for you.

What this is not

This covers the read side of RepairDesk plus core ticket workflow writes. It does not cover estimates, appointment creation, POS/sales transactions, inventory writes, payment recording, ticket image/attachment upload, or webhooks. PRs welcome if you need one of those.

Quick start

You don't need to be a developer to run this — just comfortable typing a handful of commands into a terminal. Total time: about 5 minutes.

1. Install Node.js (if you don't have it)

Download and install from nodejs.org — get the "LTS" version. This installs both node and npm. To check it worked, open a terminal and run:

node --version

You should see something like v20.x.x (anything 18 or higher is fine).

2. Get the code

If you have Git:

git clone https://github.com/codeyoc/repairdesk-mcp.git
cd repairdesk-mcp

If you don't: click the green Code button on the GitHub repo page → Download ZIP → unzip it somewhere → open a terminal in that folder.

3. Get your RepairDesk API key

In your RepairDesk admin: Settings → API. Copy the key shown there — the setup script asks for it in the next step. Treat it like a password: it grants full read/write access to your shop's data (see Security).

4. Run the setup script

node setup.mjs

This is the fastest path and handles everything: it runs npm install for you if needed, asks for your API key, asks which AI assistant you're using (Claude Code, Claude Desktop, Codex CLI, or OpenCode), and writes the config for you automatically — backing up any existing config file first. If you're on something else, it prints the config block to paste in yourself.

If you'd rather do it by hand — or your client isn't one of the four above — see Manual setup below instead. Either way, run npm install yourself first if you skip the script.

5. Try it

Ask your assistant something like "Using RepairDesk, list my 5 most recent tickets". If it comes back with real ticket data, you're done.

Manual setup

Skip this if node setup.mjs already worked for you. Otherwise, run npm install in this folder first, then wire up your client by hand:

Run this from anywhere, replacing the path with the full path to where you unzipped/cloned the folder, and the key with your real one:

claude mcp add repairdesk \
  --env REPAIRDESK_API_KEY=your_key_here \
  --env REPAIRDESK_USER_AGENT=YourShopName-MCP/1.0 \
  -- node /full/path/to/repairdesk-mcp/server.mjs

Open (or create) the config file for your OS:

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Add this (merge it with anything already in mcpServers if the file isn't empty):

{
  "mcpServers": {
    "repairdesk": {
      "command": "node",
      "args": ["/full/path/to/repairdesk-mcp/server.mjs"],
      "env": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

Save the file, then fully quit and reopen Claude Desktop (not just close the window).

Edit (or create) ~/.codex/config.toml and add:

[mcp_servers.repairdesk]
command = "node"
args = ["/full/path/to/repairdesk-mcp/server.mjs"]

[mcp_servers.repairdesk.env]
REPAIRDESK_API_KEY = "your_key_here"
REPAIRDESK_USER_AGENT = "YourShopName-MCP/1.0"

Start a new Codex session and run /mcp to confirm it connected. (Codex also has an interactive codex mcp add command if you prefer that over editing the file — check codex mcp add --help for the exact flags on your installed version.)

Open (or create) the config file for your OS:

• Mac/Linux: ~/.config/opencode/opencode.json

• Windows: %APPDATA%\opencode\opencode.json

Add this (merge it with anything already in mcp if the file isn't empty):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "repairdesk": {
      "type": "local",
      "command": ["node", "/full/path/to/repairdesk-mcp/server.mjs"],
      "enabled": true,
      "environment": {
        "REPAIRDESK_API_KEY": "your_key_here",
        "REPAIRDESK_USER_AGENT": "YourShopName-MCP/1.0"
      }
    }
  }
}

Restart OpenCode to pick it up.

The command/args/env shape used above (Claude Code/Desktop) is the de facto standard — most MCP clients follow it, just in a different settings file. Check your client's docs for where that file lives; the block itself should work as-is.

Use the full, absolute path to server.mjs (e.g. /Users/you/repairdesk-mcp/server.mjs or C:\Users\you\repairdesk-mcp\server.mjs) — a relative path will fail because your AI client doesn't run from inside this folder.

All configuration options

Everything below goes in the env/environment block your client's config uses (setup.mjs handles this for you) — not a .env file, since most MCP clients don't read one automatically. .env.example in this repo lists the same variables for reference.

Alternative: config file instead of env vars. If your setup makes env vars awkward, create a config.json (gitignored) next to server.mjs:

{
  "repairdesk_api_key": "your_key_here",
  "repairdesk_base_url": "https://api.repairdesk.co/api/web/v1"
}

It's re-read on every API call, so you can rotate the key without restarting the server. Environment variables take priority over this file when both are present.

Rate limiting — the 100/minute thing

RepairDesk's documented cap is 100 requests per minute per API key (some plans allow up to 120 — check your own plan if you're unsure). This server handles that for you automatically:

• Every outbound call is queued through a single throttle that waits at least REPAIRDESK_MIN_INTERVAL_MS (default 600ms ≈ 100/min) between requests — so asking for a big batch of tickets won't itself trigger a rate-limit error.

• If RepairDesk still returns a 429 (rate limited) — e.g. another tool is also hammering the same key — the server automatically waits and retries once before giving up.

• You don't need to configure anything for this to work. Only touch REPAIRDESK_MIN_INTERVAL_MS if you're consistently seeing rate-limit errors (raise it) or you know your plan allows a higher cap and want faster bulk lookups (lower it, carefully).

Troubleshooting

"RepairDesk API returned 401 Unauthorized" / "Unauthorized" in the response Your API key is wrong, was revoked, or wasn't picked up. Double-check the key in Settings → API in RepairDesk, and that it's spelled correctly in your MCP client's config (not a stray space, not still YOUR_REPAIRDESK_API_KEY_HERE). Fully restart your AI client after any config change — most don't reload MCP config live.

Requests fail immediately / look like they're being blocked, not authenticated RepairDesk's Cloudflare blocks requests with an empty or default-looking User-Agent. Don't set REPAIRDESK_USER_AGENT to an empty string.

"RepairDesk API rate limit hit twice in a row (429)" You're making requests faster than your key's limit even after the built-in retry. Raise REPAIRDESK_MIN_INTERVAL_MS (try 1000) in your config.

"Ticket T-XXXXX not found — could not resolve to internal ID" Check the order ID is correct and exists in this RepairDesk store. If you have the internal numeric ID instead, that works too — pass it directly.

"RepairDesk API request timed out after 15000ms" Usually a network/firewall issue reaching api.repairdesk.co, or REPAIRDESK_BASE_URL is wrong. Check you can reach that host from wherever this server is running.

Your AI assistant doesn't see the tool at all

• Confirm the path in args is absolute, not relative, and actually points at server.mjs.

• Confirm you ran npm install in that folder (missing node_modules = the server can't start).

• Fully quit and restart your AI client — don't just close the chat window.

• Run node /full/path/to/server.mjs directly in a terminal — if it errors, you'll see the actual problem instead of a generic "tool not available" from your client.

node setup.mjs says it couldn't find claude/codex on your PATH That's fine — it falls back to printing the config block for you to paste in by hand (see Manual setup). This just means that CLI isn't installed or isn't on your PATH; it doesn't mean the MCP server itself is broken.

Still stuck? Open an issue on this repo with the error message (redact your API key first if it appears anywhere in the output).

FAQ

Is this an official RepairDesk tool? No. It's independently built and maintained, using RepairDesk's public API. Use it at your own discretion.

Does this cost anything to run? No — it's just making the same API calls your RepairDesk plan already allows. There's no additional fee from this project. (Your AI assistant subscription, e.g. Claude, is separate and unrelated to this server.)

Can I use this with something other than Claude? Yes — MCP is an open standard. setup.mjs configures Claude Code, Claude Desktop, Codex CLI, and OpenCode directly; anything else that speaks MCP over stdio (Cursor, Windsurf, etc.) can use this server too, via the manual config in Manual setup.

Can I run this for multiple RepairDesk stores? Yes — register it multiple times under different names (e.g. repairdesk-store1, repairdesk-store2) in your MCP client, each with its own REPAIRDESK_API_KEY.

Will my AI assistant accidentally email/text my customers? Only repairdesk_tickets_write can trigger that, and only via a status change — which always requires an explicit confirmed: true and is flagged in the tool description when the target status is one of RepairDesk's notifying statuses. It won't happen silently.

Security

Your REPAIRDESK_API_KEY grants full read/write access to your shop's customer and financial data. Keep it in your MCP client's env config, never in a committed file. config.json and .env are gitignored here for exactly that reason — use them locally if you prefer a file over env vars, but don't commit a filled-in copy. Found a security issue? Please open an issue (or a private report if your host supports it) rather than a public PR with exploit details.

License

MIT — see LICENSE. Provided as-is, no warranty — you're responsible for how you use it against your own RepairDesk account.