tsheets-mcp

TSheets(QuickBooks Time)용 MCP 서버 — Intuit의 시간 추적, 일정 관리 및 유급 휴가(PTO) 플랫폼. 전체 공개 TSheets REST API v1을 MCP 도구로 노출합니다.

개요

• 무상태 HTTP 서비스입니다. 자격 증명은 결코 영구 저장되지 않으며, 각 요청은 헤더를 통해 자체 액세스 토큰을 제공하고 해당 단일 요청의 수명 동안에만 사용됩니다.

• 동시 요청을 지원하며, 요청별 자격 증명 격리는 전역/공유 클라이언트 인스턴스가 아닌 Python contextvars를 통해 수행됩니다.

• 진입점: POST /mcp(MCP 프로토콜) 및 GET /health(헬스 체크).

• 기본 포트: 8080(MCP_HTTP_PORT로 구성 가능).

• TSheets API에는 경로 템플릿 매개변수가 어디에도 없습니다 — 모든 식별자(ids, user_id 등)는 단일 리소스 조회의 경우에도 쿼리 문자열 매개변수로 전달됩니다. 이는 이 서버가 단순화한 것이 아니라 실제 API 설계 특성입니다.

Related MCP server: Timesheet MCP Server

범위

15개 도구로, 원래 85개 도구로 구성된 전체 API 빌드(2026-08-04)에서 축소되었습니다. 이 벤더에 대해 MSPbots가 저장해 둔 통합 구성은 정확히 6개 엔드포인트(Effective Settings, Jobcodes, Users, Customfielditem User Filters, Timesheets, Custom Fields — 모두 GET, 읽기 전용)를 호출합니다. "실제 사용 + 동일 카테고리 핵심 CRUD" 범위 결정에 따라 이 빌드는 정확히 해당 6개 카테고리를 전체로 유지합니다 — effective_settings(1, 읽기 전용, 이 리소스에는 CRUD 동사가 없음), custom_field_item_user_filters(1, 동일), jobcodes(3: 생성/조회/업데이트), users(3: 생성/조회/업데이트), timesheets(4: 생성/조회/업데이트/삭제), custom_fields(3: 생성/조회/업데이트) — 총 15개 도구입니다. 원래 85개 도구 빌드의 다른 모든 카테고리(Reports, Files, Time Off Requests (+ Entries), Schedule Events (+ Calendars), Reminders, Projects (+ Notes/Activities/Activity Replies/Activity Read Times), Notifications, Locations (+ Maps), Jobcode Assignments, Groups, Estimates (+ Items), Custom Field Items (+ Filters + Jobcode Filters), Geolocations, Timesheets Deleted, Managed Clients, Last Modified, Invitations, Geofence Configs, Current User — 28개 카테고리, 약 70개 도구)는 MSPbots가 사용하지 않으므로 완전히 제거되었습니다.

유지된 도구의 소스 데이터는 원래 TSheets 문서의 자체 GitHub 저장소(https://github.com/tsheetsteam/api_docs)를 클론하고 모든 엔드포인트별 Markdown/ERB 부분 파일(source/includes/APIReference/<Category>/_*.md.erb)에서 HTTP 메서드, 경로 및 매개변수 테이블을 파싱하여 추출되었습니다 — 이 프로그램의 다른 대형 API 벤더(ConnectSecure, Dynu, Jira Data Center, Opsgenie)에 사용된 것과 동일한 구조적 추출 후 코드 생성 방식입니다. 제거된 카테고리가 나중에 필요해지면 동일한 소스를 같은 방식으로 다시 파싱할 수 있습니다.

인증

TSheets는 벤더 자체 OAuth/API 앱 흐름을 통해 얻은 정적 액세스 토큰을 사용합니다(자체 통합 구성에서 연결된 MSPbots 내부 KB 문서 참조). MSPbots의 자체 통합 규칙은 이 토큰을 TSheets의 문서화된 형식과 일치하는 Authorization: Bearer <accessToken>으로 전송하며, 이 서버는 정확히 그대로 전달합니다.

헤더 인증 매개변수 설명

헤더가 없으면 401을 반환합니다:

{
  "error": "Missing credentials",
  "message": "This server requires the X-TSheets-Access-Token header",
  "required_headers": ["X-TSheets-Access-Token"],
  "optional_headers": []
}

환경 변수

MCP 엔드포인트

• POST /mcp — MCP 프로토콜(스트리밍 가능한 HTTP 전송)

• GET /health — 헬스 체크로, 정확히 {"status": "ok"}를 반환합니다. 이는 순수한 로컬 프로브로, TSheets API를 호출하지 않으므로 TSheets 장애가 컨테이너를 비정상으로 표시하지 않습니다.

오류 및 페이지네이션

• 도구 오류는 인밴드 JSON 봉투로 반환됩니다(예외를 발생시키거나 프로토콜 수준 오류가 아님): {"error": {"code": "...", "message": "...", "retryable": true|false}}. code는 업스트림 HTTP 상태에서 매핑된 not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error 중 하나입니다.

• TSheets API에 대한 아웃바운드 호출은 5초 연결 / 30초 읽기 제한 시간을 사용하고, 429/5xx에서 상한이 있는 지수 백오프로 최대 3회 재시도하며(Retry-After 준수), 프로세스 수명 동안 단일 연결 풀을 재사용합니다.

• 모든 retrieve_* 도구의 limit 매개변수는 기본값이 50이며, 호출자가 더 많이 요청하면 TSheets의 문서화된 페이지당 최대값인 200으로 제한됩니다(TSheets 자체 API도 기본값/최대값이 200이므로 두 상한이 여기서 일치합니다).

도구 목록

도구 이름은 tsheets_<category>_<operation> 형식으로, 소스 문서의 각 작업 ## Heading에서 파생됩니다(예: timesheets 카테고리의 "Retrieve Timesheets" → tsheets_timesheets_retrieve_timesheets). 여러 retrieve 필터 매개변수는 "필수(X, Y 또는 Z가 설정되지 않은 경우)"로 문서화되어 있습니다 — 이는 단일 하드 필수 Python 매개변수로 깔끔하게 표현할 수 없는 N-중-하나 요구 사항이므로 선택 사항으로 모델링되고 OR 제약 조건은 도구 자체의 docstring에 명시됩니다. create/update 엔드포인트의 body 매개변수는 일반 dict로 허용됩니다 — TSheets의 자체 규칙은 이를 {"data": [ {...}, ... ]}로 감쌉니다(호출당 최대 50개 객체 일괄 생성/업데이트). 각 도구별로 문서화됩니다.

테스트 예시

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-TSheets-Access-Token: <your-tsheets-access-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "tsheets_jobcodes_retrieve_jobcodes",
      "arguments": {}
    }
  }'

라이브 검증 완료 (2026-07-30): 첫 번째 테스트 액세스 토큰은 만료된 것으로 확인되었습니다(401 invalid_grant, 직접 curl로도 동일하게 확인됨 — 해당 실행에서 포착된 내용은 아래 버그 노트를 참조하세요). 그 후 새로 발급된 두 번째 액세스 토큰을 이 실행 중인 서버를 통해 엔드투엔드로 테스트했으며 실제 계정 데이터를 반환했습니다: tsheets_current_user_retrieve_the_current_user는 실제 현재 사용자 레코드(이름, 권한, PTO 잔액)와 추가 작업 코드 데이터를 반환했고, tsheets_jobcodes_retrieve_jobcodes(MSPbots가 구성한 6개 엔드포인트 중 하나와 일치)는 실제 작업 코드 레코드를 반환했습니다. 두 경우 모두 라이브 API에 대해 전체 요청/인증/응답 파이프라인이 올바르게 작동함을 확인합니다.

자체 테스트 중 수정된 버그: 초기 _raise_for_status 오류 파서는 TSheets가 항상 오류 세부 정보를 {"error": {"message": "..."}} 형태로 중첩한다고 가정했지만, TSheets는 실제로 인증 실패 시 OAuth 스타일의 평면 구조 {"error": "invalid_grant", "error_description": "..."}를 반환합니다 — 문자열 "invalid_grant"에 .get()을 호출하면 'str' object has no attribute 'get' 오류와 함께 중단되었습니다. 이 문제는 이 서버가 완료된 것으로 간주되기 전에 첫 번째(만료된) 테스트 토큰을 사용하여 포착되고 수정되었습니다.

API 참조

• 개요: https://tsheetsteam.github.io/api_docs/

• 소스(공식 Postman 컬렉션 포함): https://github.com/tsheetsteam/api_docs

알려진 한계

• 2026-08-04에 85개 도구에서 15개 도구로 축소됨. 원래 빌드는 이전 범위 결정에 따라 34개 카테고리에 걸친 전체 공개 API를 포함했습니다. 이후 범위 결정으로 MSPbots가 실제로 사용하는 정확히 6개 카테고리만 남도록 축소되었습니다(모두 전체로 유지됨 — 어떤 카테고리도 소수의 도구를 넘지 않아 카테고리별 축소는 필요하지 않았습니다) — 제거된 28개 카테고리(~70개 도구)의 전체 목록은 위의 Scope 섹션을 참조하세요. 제거된 카테고리가 나중에 필요해지면 소스 문서(https://github.com/tsheetsteam/api_docs)를 유지된 도구가 생성된 것과 같은 방식으로 다시 파싱할 수 있습니다.

• tsheets_timesheets_delete_timesheets는 공급업체 자체 문서에 따라 타임시트 레코드를 영구적으로 삭제합니다 — 파괴적/되돌릴 수 없는 작업으로 취급하고 호출 전에 사람과 확인하세요. 유지된 다른 create/update 도구도 실제 TSheets 데이터(작업 코드, 사용자, 사용자 정의 필드)를 변경합니다.

• N개 중 하나의 "필수" 필터 그룹은 모두 선택 사항으로 모델링됨 — 여러 Retrieve 엔드포인트는 매개변수를 "필수(X, Y 또는 Z가 설정되지 않은 경우)"로 문서화합니다. 이를 실제 제약 조건으로 강제하는 것은 일반 함수 시그니처로 표현할 수 없으므로 이러한 모든 매개변수는 도구 시그니처에서 선택 사항이며 OR 요구 사항은 대신 docstring에 명시됩니다. 호출자는 문서화된 제약 조건에 따라 최소한 하나를 제공해야 하며, 그렇지 않으면 라이브 API가 요청을 거부합니다.

• body 매개변수는 완전히 모델링되지 않고 유형이 지정되지 않은(dict) 상태입니다 — TSheets 자체 문서는 유형별 필드 변형을 보여줍니다(예: "Regular Timesheets"와 "Manual Timesheets"는 동일한 data 배열 내에서 서로 다른 필수 필드를 가집니다). 이는 고정된 유형 매개변수에 깔끔하게 매핑되지 않습니다. 공급업체 자체 참조(위에 링크됨)는 리소스별 정확한 스키마를 문서화합니다.