Tsheets

MCP server for TSheets (QuickBooks Time) — Intuit's time-tracking, scheduling, and PTO platform. Exposes the full public TSheets REST API v1 as MCP tools.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own access token via a header, used only for the lifetime of that single request.
• Supports concurrent requests; per-request credential isolation is done via Python contextvars, not a global/shared client instance.
• Entry points: POST /mcp (MCP protocol) and GET /health (health check).
• Default port: 8080 (configurable via MCP_HTTP_PORT).
• No path-template parameters exist anywhere in the TSheets API — every identifier (ids, user_id, etc.) is passed as a query-string parameter, even for single-resource lookups. This is a genuine API design characteristic, not a simplification made by this server.

Scope

85 tools across 34 categories, generated from the official TSheets API documentation source (https://github.com/tsheetsteam/api_docs, cloned and parsed directly — the docs' own Postman collection lists 71 requests across 29 folders, but the underlying markdown source documents several additional categories not present in that collection, e.g. TimeOffRequests/TimeOffRequestEntries, CustomFieldItemJobcodeFilters, Invitations).

MSPbots' own stored integration config for this vendor calls exactly 6 endpoints (Effective Settings, Jobcodes, Users, Customfielditem User Filters, Timesheets, Custom Fields — all GET, read-only). Per explicit user decision, this build covers the full public API including write operations (create/update/delete across every resource, plus the six built-in payroll/project report endpoints), not just those 6 calls — see Known Gaps for which tools mutate real data.

Source data was extracted by cloning the TSheets docs' own GitHub repository and parsing every per-endpoint Markdown/ERB partial file (source/includes/APIReference/<Category>/_*.md.erb) for its HTTP method, path, and parameter table — the same structured-extraction-then-codegen approach used for other large-API vendors in this program (ConnectSecure, Dynu, Jira Data Center, Opsgenie).

Authentication

TSheets uses a static access token obtained via the vendor's own OAuth/API-app flow (see MSPbots' internal KB article linked from its own integration config). MSPbots' own integration convention sends this token as Authorization: Bearer <accessToken>, matching TSheets' own documented format, and this server forwards it exactly that way.

HEADER 授权参数说明

Missing the header returns 401:

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

Environment Variables

MCP Endpoint

• POST /mcp — MCP protocol (streamable HTTP transport)
• GET /health — health check, returns {"status": "ok", "service": "tsheets-mcp", "transport": "http"}

Tool List

Tool names are tsheets_<category>_<operation>, derived from each operation's ## Heading in the source docs (e.g. "Retrieve Timesheets" in the timesheets category → tsheets_timesheets_retrieve_timesheets). Several retrieve filter parameters are documented as "required (unless X, Y, or Z is set)" — a one-of-N requirement that can't be cleanly expressed as a single hard-required Python parameter, so those are modeled as optional and the OR-constraint is spelled out in the tool's own docstring instead. body parameters for create/update endpoints are accepted as a generic dict — TSheets' own convention wraps these in {"data": [ {...}, ... ]} (bulk create/update of up to 50 objects per call), documented per-tool.

测试示例

# 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_current_user_retrieve_the_current_user",
      "arguments": {}
    }
  }'

Live-verified (2026-07-30): a first test access token turned out to be expired (401 invalid_grant, confirmed identical via direct curl — see the bug note below for what that run caught). A second, freshly-issued access token was then tested end-to-end through this running server and returned real account data: tsheets_current_user_retrieve_the_current_user returned the actual current user record (name, permissions, PTO balances) plus supplemental jobcode data, and tsheets_jobcodes_retrieve_jobcodes (matching one of MSPbots' own 6 configured endpoints) returned real jobcode records. Both confirm the full request/auth/response pipeline works correctly against the live API.

Bug fixed during self-test: the initial _raise_for_status error parser assumed TSheets always nests error details as {"error": {"message": "..."}}, but TSheets actually returns an OAuth-style flat {"error": "invalid_grant", "error_description": "..."} for auth failures — calling .get() on the string "invalid_grant" crashed with 'str' object has no attribute 'get'. This was caught and fixed using the first (expired) test token, before this server was considered done.

API Reference

• Overview: https://tsheetsteam.github.io/api_docs/
• Source (incl. official Postman collection): https://github.com/tsheetsteam/api_docs

Known Gaps

• Full API coverage was an explicit user decision, matching the pattern used for other large public APIs in this program. MSPbots itself only calls 6 read-only endpoints; every create/update/delete tool here mutates real TSheets data (timesheets, users, jobcodes, schedule events, files, etc.) or — for tsheets_timesheets_delete_timesheets and tsheets_files_delete_files in particular — permanently deletes records/attached files per the vendor's own docs. Treat any such tool as destructive/irreversible and confirm with a human before invoking.
• One-of-N "required" filter groups are modeled as all-optional — several Retrieve endpoints document a param as "required (unless X, Y, or Z is set)"; enforcing that as a real constraint isn't expressible in a plain function signature, so all such params are optional in the tool signature and the OR-requirement is spelled out in the docstring instead. Callers must supply at least one per the documented constraint or the live API will reject the request.
• body parameters are untyped (dict) rather than fully modeled — TSheets' own docs show per-type field variants (e.g. "Regular Timesheets" vs "Manual Timesheets" have different required fields within the same data array), which don't map cleanly onto fixed typed parameters; the vendor's own reference (linked above) documents the exact schema per resource.
• Source data comes from the docs' Markdown/ERB partials (not the API's actual OpenAPI/JSON-Schema, which TSheets doesn't publish) — the extraction was verified against the official Postman collection shipped in the same repository for cross-consistency (71 of 85 tools have a matching Postman request; the other 14 are documented-but-not-in-Postman categories like Time Off Requests).