RepairDesk MCP Server

MCP(Model Context Protocol) 서버로, MCP 호환 AI 어시스턴트(Claude Code, Claude Desktop, Codex CLI, OpenCode, Cursor, Windsurf 또는 기타 MCP 클라이언트)에 RepairDesk 매장 데이터에 대한 직접적인 읽기/쓰기 액세스를 제공합니다. 매장의 API 키를 지정하고 "티켓 T-15423 조회", "인보이스 8821의 연체 항목", "iPhone 화면 작업을 Dave에게 할당" 같은 질문을 시작하세요.

공식 RepairDesk 제품이 아닙니다. RepairDesk 매장이 RepairDesk 매장을 위해 만든 독립 도구입니다. 보증 없음, 사용에 따른 책임은 본인에게 있습니다(License 참조). 하지만 실제 수리점의 티켓 대기열을 운영하는 데 매일 사용되고 있으며, 개념 증명이 아닙니다.

목차

• 실제로 할 수 있는 작업

• 도구 참조

• 이것이 아닌 것

• 빠른 시작

• 수동 설정

• 모든 구성 옵션

• 문제 해결

• FAQ

• 보안

Related MCP server: TicketAI

실제로 할 수 있는 작업

AI 어시스턴트에 연결되면 웹 UI를 클릭하는 대신 RepairDesk 데이터에 직접 말을 걸 수 있습니다. 몇 가지 실제 예:

프런트 카운터 / 트리아지

• "티켓 T-15423 조회" — 전체 티켓 세부 정보: 고객, 기기, 기기별 상태, 메모.

• "Sarah Miller의 전화 상태는?" — 고객 이름/키워드로 티켓 검색.

• "Pending 또는 Waiting for Parts인 모든 항목 보여줘" — 상태별 티켓 필터링.

• "지금 Dave에게 할당된 것은?" — 기술자별 티켓 필터링.

• "John의 연락처 정보 불러와" — 이름, 전화, 이메일로 고객 조회.

워크플로 / 벤치 작업

• "T-15423에 진단 메모 추가: 화면 교체, 배터리 테스트 통과"

• "티켓 T-15490을 Dave에게 할당"

• "T-15423을 Repaired로 표시" — 서버가 먼저 확인을 요청하며, 이 상태가 RepairDesk에서 고객 SMS/이메일을 자동으로 발송한다는 점을 알려줍니다.

• "이 고객에 대한 티켓 생성: iPhone 13, 화면 교체" — 실제로 생성하기 전에 확인이 필요합니다.

금전 / 관리

• "지난달에 아직 미지불된 인보이스는?"

• "인보이스 8821의 미결제 잔액은?"

• "iPhone 13 배터리 재고가 있나요?" — 재고 검색.

• "모든 기술자 목록" / "설정된 결제 수단은?"

• "구성된 수리 카테고리/기기 유형은?" — 티켓을 만들거나 기기 모델이 시스템에서 무엇인지 진단할 때 유용한 컨텍스트.

고정된 대시보드가 아닌 실제 AI 어시스턴트를 통해 실행되므로 자연스럽게 연결할 수 있습니다. "아직 열려 있는 티켓이 있는 고객의 연체 인보이스 찾기" 같은 요청을 하면 어시스턴트가 도구를 넘나들며 처리하므로 두 화면을 수동으로 대조할 필요가 없습니다.

도구 참조

안전 레일: repairdesk_tickets_write는 상태 변경을 적용하기 전에 confirmed: true를 요구하며, 대상 상태가 RepairDesk가 고객에게 자동 알림을 보내는 상태(Repaired, Ready for Pickup, Completed, Waiting on Customer, Waiting For Quote, Cancelled)인 경우 경고합니다. 이 기능이 작동하도록 특별히 할 일은 없습니다. 어시스턴트가 확인 프롬프트를 전달하면 "예"라고 답하기만 하면 됩니다.

유용한 세부 정보: 티켓 조회/쓰기는 RepairDesk의 주문 ID 형식(T-15423) 또는 내부 숫자 티켓 ID를 모두 허용합니다. 어떤 형식을 가지고 있는지 알 필요 없이 서버가 자동으로 해결합니다.

이것이 아닌 것

이것은 RepairDesk의 읽기 측면과 핵심 티켓 워크플로 쓰기를 다룹니다. 견적, 약속 생성, POS/판매 거래, 재고 쓰기, 결제 기록, 티켓 이미지/첨부 파일 업로드, 웹훅은 다루지 않습니다. 이러한 기능이 필요하면 PR을 환영합니다.

빠른 시작

개발자가 아니어도 실행할 수 있습니다. 터미널에 몇 가지 명령을 입력할 수 있으면 됩니다. 총 소요 시간: 약 5분.

1. Node.js 설치(없는 경우)

nodejs.org에서 다운로드하여 설치하세요. "LTS" 버전을 받으세요. 그러면 node와 npm이 모두 설치됩니다. 제대로 설치되었는지 확인하려면 터미널을 열고 다음을 실행하세요:

node --version

v20.x.x 같은 것이 보여야 합니다(18 이상이면 괜찮습니다).

2. 코드 가져오기

Git이 있는 경우:

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

없는 경우: GitHub 저장소 페이지에서 녹색 Code 버튼을 클릭 → Download ZIP → 원하는 곳에 압축 해제 → 해당 폴더에서 터미널을 엽니다.

3. RepairDesk API 키 가져오기

RepairDesk 관리자에서: Settings → API. 거기에 표시된 키를 복사하세요. 다음 단계에서 설정 스크립트가 요청합니다. 비밀번호처럼 취급하세요. 매장 데이터에 대한 전체 읽기/쓰기 액세스를 제공합니다(보안 참조).

4. 설정 스크립트 실행

node setup.mjs

이것이 가장 빠른 방법이며 모든 것을 처리합니다: 필요한 경우 npm install을 실행하고, API 키를 묻고, 사용 중인 AI 어시스턴트(Claude Code, Claude Desktop, Codex CLI 또는 OpenCode)를 묻고, 기존 구성 파일을 먼저 백업한 후 자동으로 구성을 작성합니다. 다른 것을 사용하는 경우 직접 붙여넣을 구성 블록을 출력합니다.

직접 하거나 클라이언트가 위 네 가지 중 하나가 아닌 경우 아래 수동 설정을 참조하세요. 어느 쪽이든 스크립트를 건너뛰면 먼저 직접 npm install을 실행하세요.

5. 시도해 보기

어시스턴트에게 "RepairDesk를 사용하여 최근 티켓 5개를 나열해 줘" 같은 질문을 해 보세요. 실제 티켓 데이터가 반환되면 완료입니다.

수동 설정

node setup.mjs가 이미 작동했다면 건너뛰세요. 그렇지 않으면 이 폴더에서 먼저 npm install을 실행한 다음 클라이언트를 직접 연결하세요:

어디서든 다음을 실행하되, 경로를 폴더를 압축 해제/복제한 전체 경로로, 키를 실제 키로 바꾸세요:

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

운영 체제에 맞는 구성 파일을 열거나 만드세요:

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

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

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

다음을 추가하세요(파일이 비어 있지 않으면 mcpServers에 이미 있는 내용과 병합):

{
  "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"
      }
    }
  }
}

파일을 저장한 다음 Claude Desktop을 완전히 종료하고 다시 열으세요(창을 닫는 것만으로는 안 됩니다).

~/.codex/config.toml을 편집(또는 생성)하고 다음을 추가하세요:

[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"

새 Codex 세션을 시작하고 /mcp를 실행하여 연결되었는지 확인하세요. (Codex에는 파일을 편집하는 대신 사용할 수 있는 대화형 codex mcp add 명령도 있습니다. 설치된 버전의 정확한 플래그는 codex mcp add --help를 확인하세요.)

운영 체제에 맞는 구성 파일을 열거나 만드세요:

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

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

다음을 추가하세요(파일이 비어 있지 않으면 mcp에 이미 있는 내용과 병합):

{
  "$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"
      }
    }
  }
}

OpenCode를 다시 시작하여 적용하세요.

위에서 사용한 command/args/env 형식(Claude Code/Desktop)은 사실상 표준입니다. 대부분의 MCP 클라이언트가 이 형식을 따르며, 설정 파일 위치만 다릅니다. 클라이언트 문서에서 해당 파일 위치를 확인하세요. 블록 자체는 그대로 작동해야 합니다.

server.mjs의 전체 절대 경로를 사용하세요(예: /Users/you/repairdesk-mcp/server.mjs 또는 C:\Users\you\repairdesk-mcp\server.mjs). 상대 경로는 AI 클라이언트가 이 폴더 안에서 실행되지 않으므로 실패합니다.

모든 구성 옵션

아래 모든 항목은 클라이언트 구성의 env/environment 블록에 들어갑니다(setup.mjs가 처리). 대부분의 MCP 클라이언트는 .env 파일을 자동으로 읽지 않으므로 .env 파일이 아닙니다. 이 저장소의 .env.example에는 동일한 변수가 참조용으로 나열되어 있습니다.

대안: 환경 변수 대신 설정 파일 사용. 환경 변수 설정이 번거로운 경우, server.mjs 옆에 config.json(gitignore 처리됨)을 생성하세요:

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

이 파일은 모든 API 호출 시 다시 읽히므로, 서버를 재시작하지 않고도 키를 교체할 수 있습니다. 두 설정이 모두 존재하는 경우 환경 변수가 이 파일보다 우선합니다.

속도 제한 — 분당 100회 제한

RepairDesk의 문서화된 상한은 API 키당 분당 100회 요청입니다(일부 요금제는 최대 120회 허용 — 확실하지 않다면 본인 요금제를 확인하세요). 이 서버는 이를 자동으로 처리합니다:

• 모든 외부 호출은 요청 사이에 최소 REPAIRDESK_MIN_INTERVAL_MS(기본값 600ms ≈ 분당 100회)를 대기하는 단일 스로틀을 통해 큐에 들어갑니다 — 따라서 대량의 티켓을 요청해도 자체적으로 속도 제한 오류가 발생하지 않습니다.

• RepairDesk가 여전히 429(속도 제한)를 반환하는 경우 — 예: 다른 도구가 동일한 키를 동시에 사용 중인 경우 — 서버는 자동으로 대기 후 한 번 재시도한 다음 포기합니다.

• 이 기능이 작동하도록 별도로 설정할 필요는 없습니다. 속도 제한 오류가 지속적으로 발생하는 경우에만 REPAIRDESK_MIN_INTERVAL_MS를 조정하세요(값을 높이거나, 요금제에서 더 높은 상한이 허용되고 더 빠른 대량 조회가 필요하다면 신중하게 값을 낮추세요).

문제 해결

"RepairDesk API returned 401 Unauthorized" / 응답에 "Unauthorized" 표시 API 키가 잘못되었거나, 폐기되었거나, 인식되지 않았습니다. RepairDesk의 설정 → API에서 키를 다시 확인하고, MCP 클라이언트 설정에 올바르게 입력되었는지 확인하세요(불필요한 공백이 있거나 YOUR_REPAIRDESK_API_KEY_HERE 그대로 남아 있지 않은지). 설정 변경 후 AI 클라이언트를 완전히 재시작하세요 — 대부분의 클라이언트는 MCP 설정을 실시간으로 다시 로드하지 않습니다.

요청이 즉시 실패 / 인증 문제가 아니라 차단된 것처럼 보임 RepairDesk의 Cloudflare는 User-Agent가 비어 있거나 기본값처럼 보이는 요청을 차단합니다. REPAIRDESK_USER_AGENT를 빈 문자열로 설정하지 마세요.

"RepairDesk API rate limit hit twice in a row (429)" 내장된 재시도 후에도 키의 한도를 초과하는 속도로 요청하고 있습니다. 설정에서 REPAIRDESK_MIN_INTERVAL_MS 값을 높이세요(1000 시도).

"Ticket T-XXXXX not found — could not resolve to internal ID" 주문 ID가 올바르고 이 RepairDesk 스토어에 존재하는지 확인하세요. 내부 숫자 ID가 있다면 그것도 작동합니다 — 직접 전달하세요.

"RepairDesk API request timed out after 15000ms" 일반적으로 api.repairdesk.co에 도달하는 네트워크/방화벽 문제이거나 REPAIRDESK_BASE_URL이 잘못된 경우입니다. 이 서버가 실행 중인 환경에서 해당 호스트에 접근할 수 있는지 확인하세요.

AI 어시스턴트가 도구를 전혀 인식하지 못함

• args의 경로가 상대 경로가 아닌 절대 경로이고 실제로 server.mjs를 가리키는지 확인하세요.

• 해당 폴더에서 npm install을 실행했는지 확인하세요(node_modules가 없으면 서버가 시작되지 않습니다).

• AI 클라이언트를 완전히 종료하고 재시작하세요 — 채팅 창만 닫지 마세요.

• 터미널에서 node /full/path/to/server.mjs를 직접 실행하세요 — 오류가 발생하면 클라이언트의 일반적인 "도구를 사용할 수 없음" 메시지 대신 실제 문제를 확인할 수 있습니다.

node setup.mjs가 PATH에서 claude/codex를 찾을 수 없다고 표시 괜찮습니다 — 수동으로 붙여넣을 수 있도록 설정 블록을 출력하는 방식으로 대체됩니다(수동 설정 참조). 이는 해당 CLI가 설치되지 않았거나 PATH에 없다는 뜻일 뿐, MCP 서버 자체가 고장난 것은 아닙니다.

여전히 해결되지 않았나요? 이 저장소에 오류 메시지와 함께 이슈를 열어주세요(출력에 API 키가 포함된 경우 먼저 삭제하세요).

FAQ

이것은 공식 RepairDesk 도구인가요? 아니요. RepairDesk의 공개 API를 사용하여 독립적으로 구축되고 유지관리되는 도구입니다. 사용에 따른 책임은 본인에게 있습니다.

실행 비용이 드나요? 아니요 — 이미 RepairDesk 요금제에서 허용하는 것과 동일한 API 호출을 수행할 뿐입니다. 이 프로젝트에서 추가 비용은 없습니다. (Claude와 같은 AI 어시스턴트 구독료는 별개이며 이 서버와 무관합니다.)

Claude 외에 다른 도구와도 사용할 수 있나요? 네 — MCP는 개방형 표준입니다. setup.mjs는 Claude Code, Claude Desktop, Codex CLI, OpenCode를 직접 구성합니다. stdio를 통해 MCP를 지원하는 다른 도구(Cursor, Windsurf 등)도 수동 설정의 수동 구성을 통해 이 서버를 사용할 수 있습니다.

여러 RepairDesk 스토어에 대해 실행할 수 있나요? 네 — MCP 클라이언트에서 각각 다른 이름(예: repairdesk-store1, repairdesk-store2)으로 여러 번 등록하고, 각각 고유한 REPAIRDESK_API_KEY를 사용하세요.

AI 어시스턴트가 실수로 고객에게 이메일/문자를 보낼 수 있나요? repairdesk_tickets_write만이 그런 작업을 트리거할 수 있으며, 상태 변경을 통해서만 가능합니다 — 이 경우 항상 명시적인 confirmed: true가 필요하고, 대상 상태가 RepairDesk의 알림 발송 상태 중 하나인 경우 도구 설명에 표시됩니다. 조용히 발생하지 않습니다.

보안

REPAIRDESK_API_KEY는 매장의 고객 및 재무 데이터에 대한 전체 읽기/쓰기 권한을 부여합니다. MCP 클라이언트의 환경 설정에 보관하고, 커밋된 파일에는 절대 넣지 마세요. config.json과 .env는 바로 그 이유로 여기서 gitignore 처리되어 있습니다 — 환경 변수보다 파일을 선호한다면 로컬에서 사용하되, 값이 채워진 복사본을 커밋하지 마세요. 보안 문제를 발견했나요? 악용 세부 정보가 포함된 공개 PR 대신 이슈(또는 호스트가 지원하는 경우 비공개 보고)를 열어주세요.

라이선스

MIT — LICENSE 참조. 있는 그대로 제공되며 보증이 없습니다 — 본인의 RepairDesk 계정에 대해 사용하는 방식에 대한 책임은 사용자에게 있습니다.