Jobber MCP Server: Claude, ChatGPT 또는 Copilot을 Jobber에 연결

Adeocode 제작: 주택 서비스 업체를 위한 맞춤 소프트웨어

우리는 HVAC, 배관, 지붕, 코팅, 울타리 및 조경 업체를 위해, 이미 사용 중인 도구 위에 통합 및 내부 시스템을 구축합니다. 코드는 이 커넥터를 포함하여 고객이 소유합니다. 15분 상담 예약하기

오픈소스 Model Context Protocol 서버로, Claude, ChatGPT 또는 Microsoft Copilot이 Jobber에서 실시간 데이터(고객, 작업, 견적, 인보이스, 매출 및 일정)를 읽을 수 있게 해줍니다. 일상적인 영어로 질문하면 계정에서 답을 얻을 수 있으며, 채팅 창으로 내보낼 필요가 없습니다.

TL;DR: 도구 12개. 읽기 전용이라 계정을 변경할 수 없습니다. stdio를 통해 사용자 머신에서 실해되거나, ChatGPPT 및 Copilot Studio를 위해 Streamable HTTP를 통한 원격 서버로 실해됩니다. 모든 리를 Jobber의 10,000포인트 한도에 맞줘 예산을 책정하는데, 이 부븐에서 대부븐의 Jobber 통합이 실수합니다. OAuth 토큰은 AES-256-GCM으로 저장 시 암호화됩니다. 릴레이 서버도 중개인도 없습니다. MIT 라이선스, 영원히 무료입니다.

대상: Jobber에서 사업을 운영하는 오너와 사무실 관리자, 그리고 그들을 위해 개발하는 개발자. 구성 파일에 블록 하나를 붙여넣을 수 있다면 사용할 수 있습니다.

[!TIP] 개발자가 아니신가요? 개발자일 필오가 없습니다.

아래 단계는 JSON 파일 편집에 익숙한 사람을 가정합니다. 그렇지 않다면 저희가 설정해 드립니다: 여러분만의 Jobber 앱, 범위가 제한된 자격 증명, 그리고 팀원 한 명이 직접 과정을 진행합니다.

Jobber API로 구축하는 것 보기 또는 15분 상담 예약하기

바로가기: 무엇을 물어볼 수 있나요 . 왜 이것이 다른가요 . 안전성 . 설정 . 도구 . 비용 표 . 더 필요한가요?

무엇을 물어볼 수 있나요

연결되면 다음 질문들은 아홉 번의 클릭 대신 한 줄 질문이 됩니다.

금전

• "30일이 지난 인보이스는 무엇인가요?"

• "지금 우리가 받을 금액은 얼마인가요?"

• "지난 분기에 얼마를 청구했나요?"

• "올해 월별 매출을 보여주세요"

견적

• "발송된 후 회신이 없는 견적은 무엇인가요?"

• "고객을 기다리고 있는 가장 오래된 견적은 무엇인가요?"

• "대기 중인 견적에 얼마가 쌓여 있나요?"

고객

• "Harbour Coatings를 불러와 줘"

• "이 고객과의 거래 내역을 요약해 줘"

• "지난번에 얼마를 청구했나요?"

• "이 전화번호로 연락처를 찾아줘"

업무

• "이번 주 일정은 어떻게 되나요?"

• "지난달에 상태별로 몇 건의 작업을 예약했나요?"

• "확인하지 않은 새 요청이 있나요?"

• "지금 일정이 잡히지 않은 것은 무엇인가요?"

모든 답변은 각 요청 시 Jobber의 실시간 데이터에서 가져옵니다. 캐시되는 것은 없으며, 커넥터가 계정에 관한 어떤 정보도 저장하지 않습니다.

Related MCP server: Jobber MCP Connector

왜 이것이 다른가

Jobber는 API 사용량을 단순 요청 수가 아니라 쿼리 비용으로 측정합니다. 10,000포인트가 주어지며, 초당 500포인트씩 재충전됩니다. 별도의 상한선으로 5분마다 2,500회 요청으로 제한됩니다.

이것은 들리는 것보다 중요합니다. 저희는 프로덕션에서 Jobber 통합을 구축하며, 그중 하나에서 모든 호출의 비용을 기록했습니다. KPI 대시보드를 한 번 로드하는 데 4152회의 API 호출로 13,45620,762포인트가 측정되었습니다. 한 화면이 10,000포인트 예산에 맞서는 셈입니다.

그리고 거의 모든 사람이 걸리는 부분이 있습니다. Jobber가 요청을 제한하면 HTTP 200으로 응답하고 오류를 응답 본문에 넣습니다. 재시도 라이브러리는 상태 코드를 기준으로 삼아 200을 성공으로 읽고 아무것도 반환하지 않습니다.

이 커넥터는 이 두 가지 사실을 중심으로 구축되었습니다:

• 모든 도구는 최대 비용을 선언하고, 무언가를 소비하기 전에 남은 예산을 확인합니다.

• 200 응답 내부의 제한 신호를 감지하고, 재충전을 기다린 후 호출을 한 번 재시도합니다.

• 페이지 크기는 도구별로 제한되므로, 한 질문이 다음 질문의 한도를 고갈시킬 수 없습니다.

• 대기가 길어질 경우, 그 사실을 알리고 멈추는 대신 빠르게 실패 처리합니다.

전체 측정 결과는 공개되어 있습니다: 프로덕션에서 측정한 Jobber API 속도 제한

또한 아래에서 모든 도구의 측정 비용을 읽을 수 있습니다. 그 숫자는 각 도구를 실제 계정에 대해 실행하는 스크립트에서 나온 것이지 추정치가 아닙니다.

안전성: 할 수 있는 것과 할 수 없는 것

읽기 전용입니다. 버전 1은 읽기 도구만 제공합니다. 조회, 집계, 요약을 할 수 있습니다. 작업을 만들거나, 인보이스를 보내거나, 방문 일정을 옮길 수 없으므로, 최악의 실패는 잘못된 조치가 아니라 잘못된 답변입니다. 쓰기 도구는 하나씩 추가될 예정이며, 각각 명시적 승인 단계를 거치고 모두 기록됩니다.

모델은 자체 쿼리를 작성하지 않습니다. 모든 GraphQL 문서는 src/jobber/queries.ts에 고정되어 있고 검토되었습니다. 모델은 호출할 도구와 전달할 인수만을 선택하며, 그것이 전부입니다. 원시 쿼리 도구가 없으므로 접근 범위와 API 비용을 예측 가능하게 유지합니다.

자격 증명은 사용자 머신에 유지됩니다. 직접 Jobber 개발자 앱을 등록합니다. Jobber 계정 관리자가 Jobber 자체 로그인 페이지를 통해 승인하므로, 커넥터는 비밀번호를 절대 볼 수 없습니다. 토큰은 ~/.jobber-mcp/ 아래에 AES-256-GCM으로 암호화되어 저장되며, 키는 디스크에 평문으로 저장되는 대신 OS 키체인에 보관됩니다.

어떤 것도 저희를 경유하지 않습니다. 커넥터는 사용자 하드웨어에서 실행되며 Jobber와 직접 통신합니다. 중간에 Adeocode 클라우드 서비스가 없습니다. 클라우드 서비스 자체가 없기 때문입니다.

모든 호출은 로컬에 기록됩니다. ~/.jobber-mcp/audit.log는 각 도구 호출을 타임스탬프, 인수, 결과와 함께 기록합니다. 토큰과 비밀 정보는 절대 기록되지 않으며, find_client의 검색어는 고객의 이름이나 전화번호를 포함할 수 있으므로 저장하는 대신 해시됩니다. get_audit_log 도구로 다시 읽을 수 있습니다.

한 가지 솔직한 한계. 커넥터는 Jobber API가 제공하는 데이터만 읽습니다. 팀 활용률, 개인별 시간, 작업별 비용이나 이익은 포함되어 있지 않습니다. 이러한 것들은 커넥터 이상의 작업이 필요하며, 이 페이지 하단에서 다룹니다.

요구 사항

• Node.js 18 이상: nodejs.org/en/download

• MCP 클라이언트: Claude Desktop, Claude Code, Cursor, ChatGPT(개발자 모드) 또는 Microsoft Copilot Studio

• API 접근 권한이 있는 Jobber 계정과, 그 계정에서 개발자 앱을 승인할 수 있는 사람. Jobber는 전체 API 접근 권한을 최상위 요금제에만 제공하므로 getjobber.com/pricing에서 먼저 요금제를 확인하세요.

설정

세 단계, 처음에는 약 15분이 걸립니다.

1단계: Jobber 개발자 앱 등록

1. developer.getjobber.com에 접속하여 Jobber 관리자 계정으로 로그인하세요.

2. 새 앱을 만드세요. 알아볼 수 있는 이름을 지정하세요. 예를 들어 Claude Connector.

3. 리디렉션 URI를 정확히 http://127.0.0.1:5679/callback으로 설정하세요.

4. 저장한 다음 Client ID와 Client Secret을 복사하세요.

2단계: AI 클라이언트에 추가

Claude Desktop. 구성 파일을 엽니다:

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

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

mcpServers 안에 다음을 추가하되, 자신의 값으로 바꾸세요:

{
  "mcpServers": {
    "jobber": {
      "command": "npx",
      "args": ["-y", "@adeocode/jobber-mcp"],
      "env": {
        "JOBBER_CLIENT_ID": "your-jobber-client-id",
        "JOBBER_CLIENT_SECRET": "your-jobber-client-secret"
      }
    }
  }
}

다른 서버가 이미 구성되어 있다면, 이 블록을 추가하기 전에 마지막 서버 항목 뒤에 쉼표를 추가하세요. 그런 다음 Claude Desktop을 완전히 종료하고 다시 엽니다.

Claude Code: claude mcp add jobber -- npx -y @adeocode/jobber-mcp

Cursor: Cursor의 MCP 설정에 동일한 JSON 블록을 넣습니다.

ChatGPT 및 Microsoft Copilot Studio: 둘 다 원격 서버에만 연결하므로 아래의 HTTP 전송을 사용하세요.

3단계: 한 번 로그인

새 대화에서 다음과 같이 말하세요:

authenticate with Jobber

브라우저에서 Jobber 로그인 페이지가 열립니다. Jobber 관리자가 앱을 승인합니다. 연결 성공 메시지가 표시되면 어시스턴트로 돌아가 다음을 시도하세요:

which invoices are past 30 days?

나중에 연결을 확인하려면 auth_status를 요청하세요.

[!TIP] 막혀 있나요, 아니면 처음부터 제대로 처리하고 싶나요?

저희가 앱을 등록하고, 여러분의 계정에 연결하며, 팀원 한 명이 사용법을 익히도록 안내합니다. 그런 다음 아직 답할 수 없는 부분을 보여드리는데, 그것이 보통 가장 흥미로운 부분입니다.

Jobber AI 서비스 보기 또는 15분 상담 예약하기

ChatGPT 및 Copilot Studio용 HTTP 전송

ChatGPT의 개발자 모드와 Microsoft Copilot Studio는 모두 인터넷을 통해 접근할 수 있는 서버가 필요하므로, 커넥터를 HTTP 모드로 실행하고 <MCP_BASE_URL>/mcp를 가리키게 하세요.

TRANSPORT=http \
MCP_BASE_URL=https://your-host.example.com \
MCP_API_KEY="$(openssl rand -hex 32)" \
JOBBER_CLIENT_ID=your-client-id \
JOBBER_CLIENT_SECRET=your-client-secret \
npx -y @adeocode/jobber-mcp

공개적으로 노출하기 전에 이 내용을 읽으세요. 서버는 MCP_API_KEY가 없으면 HTTP 모드로 시작을 거부합니다. 값을 설정하지 않으면 /mcp와 Jobber에서 읽을 수 있는 모든 것이 포트에 도달하는 모든 사람에게 열리기 때문입니다. MCP_ALLOW_NO_API_KEY=true는 그 앞에서 다른 무언가가 이미 인증을 강제할 때만 설정하세요. /mcp, /oauth/start 및 /oauth/callback은 DNS 리바인딩 보호를 위해, Host 또는 Origin 헤더가 MCP_BASE_URL과 일치하지 않는 요청을 거부합니다. HTTPS를 사용하세요. OAuth 콜백의 바인딩 쿠키는 HTTPS를 사용할 때만 Secure로 표시됩니다. 각 세션은 생성 시 제공된 API 키의 해시에 바인딩되므로, 유출된 mcp-session-id만으로는 재생할 수 없습니다. 또한 세션은 30분간 유휴 상태이거나 24시간이 지나면 정리됩니다. /health는 {ok: true}만 반환하며 그 외에는 아무것도 반환하지 않습니다.

사용 가능한 도구

어시스턴트가 질문에서 이 도구들을 자동으로 선택합니다. 이름을 직접 호출할 일은 없습니다.

계정 읽기(도구 8개)

연결 관리(도구 4개)

리소스

페이지네이션

모든 목록 도구는 선택적 cursor를 받습니다. 한 페이지에 들어갈 수 있는 것보다 더 많은 레코드가 있으면 응답에 note("N개 더 사용 가능")와 next_cursor가 모두 포함됩니다. 다음 호출에서 해당 값을 cursor로 전달하고, next_cursor가 더 이상 오지 않을 때까지 반복합니다.

client_history는 이를 jobs_cursor, quotes_cursor, invoices_cursor, payments_cursor로 섹션별로 나누며, requests_inbox는 새 요청에 cursor를, 예약되지 않은 요청에 unscheduled_cursor를 사용합니다. payments_cursor는 다른 것들과 다르게 동작합니다. 결제는 클라이언트 수준 연결 없이 인보이스별로 중첩되어 있으므로, 이를 전달하면 더 많은 결제가 있던 인보이스의 추가 결제를 가져오며 해당 응답에는 payments 섹션만 포함됩니다. 각 결제에는 invoice_id와 invoice_number가 포함되어 다시 연결할 수 있습니다.

비용 표

측정된 값이며 추정치가 아닙니다. 위에서 설명한 10,000포인트 예산을 기준으로, 호출당 비용 로깅을 사용해 실제 Jobber 계정에서 각 도구를 실행하여 생성되었습니다.

npm run build && npm run measure-costs로 다시 생성하세요. 이 값들을 수동으로 입력하지 마세요.

구성

모든 변수는 .env.example에 문서화되어 있습니다. 내장 서버를 환경 변수를 직접 전달하는 클라이언트를 통하지 않고 npm start로 직접 실행하는 경우, .env는 작업 디렉터리가 아니라 설치된 패키지 디렉터리의 package.json 옆에서 읽힙니다. 해당 위치에 두거나 셸에서 변수를 내보내세요.

문제 해결

"API budget refilling, try again in Ns." Jobber의 비용 기반 속도 제한이 제 역할을 하고 있습니다. 커넥터는 예산을 추적하고 5초 이하의 짧은 재충전은 자동으로 기다립니다. 여기에는 Jobber가 HTTP 200 안에 보내는 THROTTLED 응답도 포함됩니다. 대기가 그보다 길어질 때만 이 메시지가 표시되며, 그 시점에는 멈추지 않고 빠르게 실패합니다. 잠시 후 다시 시도하세요.

"Jobber restricts this data to accounts on its top-tier plan." Jobber는 전체 API 액세스를 최상위 요금제로 제한합니다. getjobber.com/pricing에서 내 요금제를 확인하세요.

OAuth가 오류 페이지로 다시 돌아옵니다. JOBBER_CLIENT_ID와 JOBBER_CLIENT_SECRET이 개발자 앱과 정확히 일치하는지, Jobber에 등록된 리디렉션 URI가 커넥터가 사용하는 URI와 일치하는지 확인하세요. HTTP 모드에서는 MCP_BASE_URL에서 파생됩니다.

포트 5679가 이미 사용 중입니다. JOBBER_REDIRECT_PORT를 사용 가능한 포트로 설정하고 Jobber 앱의 리디렉션 URI도 그에 맞게 업데이트하세요.

"Token file exists but decryption failed." 암호화 키가 토큰 파일을 쓸 때의 키와 더 이상 일치하지 않습니다. 일반적으로 키체인 항목이 제거되었거나, 머신이 변경되었거나, ENCRYPTION_KEY가 다르게 설정되었기 때문입니다. logout을 실행한 다음 authenticate를 다시 실행하세요.

감사 로그

모든 도구 호출은 JSONL 형식으로 ~/.jobber-mcp/audit.log에 기록되며, 디렉터리는 0700, 파일은 0600 권한을 가집니다. 액세스 토큰, 리프레시 토큰, 클라이언트 시크릿, 비밀번호, 암호화 키는 절대 기록되지 않습니다. 삭제 목록은 src/utils/auditLog.ts를 참조하세요. find_client의 search_term은 평문으로 저장되지 않고 해시 처리되므로, 고객의 이름, 이메일, 전화번호를 노출하지 않으면서 항목 간에 연관 지을 수 있습니다. 로그를 업무상 민감한 정보로 취급하고 그에 따라 머신 접근을 제한하세요.

파일은 10MB를 넘기면 한 번 순환됩니다. 현재 파일은 audit.log.1이 되며 이전 순환 파일을 덮어쓰고 새 로그가 시작됩니다. 이는 단일 세대 순환 방식이지 완전한 logrotate 설정이 아닙니다. get_audit_log 도구로 다시 읽을 수 있습니다. 줄 중간에 중단된 쓰기 등으로 인해 파싱에 실패한 줄이 있으면 응답에 corrupted_lines 수가 표시됩니다.

커넥터보다 더 많은 것이 필요하신가요?

이 커넥터는 Jobber 계정을 읽습니다. 그 데이터 위에 무언가를 구축하지는 않으며, 사업주가 가장 궁금해하는 질문들은 대개 API가 제공하는 범위 바로 밖에 있습니다. 예: 팀원 활용률, 개인별 시간, 작업별 비용과 이익, 또는 백그라운드에서 자체 데이터베이스로 동기화되어 빠른 속도를 유지하는 대시보드.

그것이 바로 우리가 하는 작업입니다. Jobber API 위에 우리가 구축하는 것 보기, 전체 도구 목록과 FAQ가 있는 개요를 읽거나, 15분 통화 예약을 하고 Jobber가 답해 주길 가장 바라는 질문을 가져오세요. Zap으로 해결된다면 그 말을 먼저 들려드리겠습니다.

영원히 무료

이 저장소의 코드는 MIT 라이선스를 유지하며, 새로운 릴리스도 MIT를 유지합니다. 여기에는 기능이 제한되거나, 시간 제한이 있거나, 유료 등급을 위해 보류된 것이 없습니다. 우리는 이 도구로는 만들 수 없는 시스템을 구축하여 수익을 얻습니다.

이 프로젝트 지원하기

우리는 기부를 받지 않습니다. 시간을 절약해 주었다면, 실제로 도움이 되는 것들은 다음과 같습니다:

• 저장소에 스타를 달아 주세요. 다른 업체들이 이 프로젝트를 찾는 방법입니다.

• Jobber를 사용하는 다른 업체에 알려 주세요.

• 이 도구가 제대로 처리하지 못하는 Jobber API 사례를 발견하면 이슈를 열어 주세요.

우리는 누구인가

Adeocode는 주거 서비스 업종을 위한 맞춤 소프트웨어를 구축합니다: HVAC, 배관, 지붕, 코팅, 울타리, 조경 및 관련 업종. 업체가 이미 운영하는 방식을 중심으로 구축된 통합, 대시보드, 내부 시스템을 클라이언트가 완전히 소유합니다.

우리는 독립적인 개발자입니다. Jobber, Housecall Pro, ServiceTitan 또는 Anthropic과 제휴 관계가 없으며, 그들로부터 소개 수수료를 받지 않습니다. 그들의 제품에 대해 우리가 게시하는 모든 내용에는 검증한 날자가 포함됩니다.

• 웹: adeocode.com

• 통화 예약: 창업자와 15분

기여하기

이슈와 풀 리퀘스트는 언제나 환영합니다. 이 도구가 제대로 처리하지 못하는 Jobber API 엣지 케이스를 발견하면 시나리오와 예제 요청을 포함해 이슈를 열어 주세요. 버전 1 범위에 맞는 읽기 전용 도구는 풀 리퀘스트로 환영합니다.

개발

npm install
npm test
npm run build
npm run lint

src/jobber/queries.ts의 모든 GraphQL 문서는 배포 전에 고정된 JOBBER_GRAPHQL_VERSION의 Jobber Developer Center GraphiQL에 대해 검증됩니다. 모든 문서를 대상으로 한 전체 재검증이 2026-08-26에 완료되었으며, 페이지네이션 및 시간대 변경 이후의 schedule_lookup과 requests_inbox도 포함됩니다. VERIFY-IN-GRAPHIQL 표시는 남아 있지 않습니다.

라이선스

MIT (c) Adeocode. LICENSE를 참조하세요.